使用 Parcel 构建库

安装

¥Installation

在开始之前，你需要安装 Node 和 Yarn 或 npm，并为你的项目创建一个目录。然后，使用 Yarn 安装 Parcel：

¥Before we get started, you'll need to install Node and Yarn or npm, and create a directory for your project. Then, install Parcel using Yarn:

yarn add --dev parcel

或者使用 npm 运行时：

¥Or when using npm run:

npm install --save-dev parcel

项目设置

¥Project setup

现在 Parcel 已安装，让我们为我们的库设置一个 package.json 文件。我们将使用 source 字段来引用我们的源文件，并创建 main 目标作为构建的输出文件。这将被使用我们库的其他工具（例如打包器或 Node.js）使用。

¥Now that Parcel is installed, let’s setup a package.json file for our library. We'll use the source field to reference our source files, and create a main target as the output file of our build. This will be consumed by other tools that use our library (e.g. bundlers or Node.js).

package.json:

{
  "name": "my-library",
  "version": "1.0.0",
  "source": "src/index.js",
  "main": "dist/main.js",
  "devDependencies": {
    "parcel": "latest"
  }
}

上面的示例使用 src/index.js 作为我们库的源代码，所以接下来让我们创建该文件。在此示例中，我们使用 JavaScript 文件，但我们也可以在此处引用 TypeScript 文件或任何其他编译为 JavaScript 的语言。

¥The above example uses src/index.js as the source code for our library, so let's create that file next. In this example, we're using a JavaScript file, but we could also reference a TypeScript file or any other language that compiles to JavaScript here.

src/index.js:

export function add(a, b) {
  return a + b;
}

现在，我们的库导出一个名为 add 的函数，它将两个参数相加并返回结果。由于这是使用 export 关键字以 ES 模块语法编写的，因此 Parcel 会按照默认情况在 main 字段中将我们的代码编译为 CommonJS 模块。

¥Now, our library exports a single function called add, which adds its two parameters together and returns the result. Since this is written in ES module syntax using the export keyword, Parcel will compile our code to a CommonJS module as expected by default in the main field.

要构建我们的库，请在项目目录中运行 npx parcel build。Parcel 将构建你的源代码并在 dist/main.js 中输出由 main 字段引用的 JavaScript 文件。

¥To build our library, run npx parcel build within the project directory. Parcel will build your source code and output a JavaScript file in dist/main.js as referenced by the main field.

包脚本

¥Package scripts

到目前为止，我们一直在直接运行 parcel CLI，但在 package.json 文件中创建一些脚本可以使这变得更容易。我们还将设置一个 watch 脚本，该脚本将监视源文件的更改并自动重建，因此你无需在开发过程中在进行更改时手动运行 build 脚本。

¥So far, we’ve been running the parcel CLI directly, but it can be useful to create some scripts in your package.json file to make this easier. We'll also setup a watch script which will watch your source files for changes and rebuild automatically so you don't need to run the build script manually in development as you make changes.

package.json:

{
  "name": "my-library",
  "version": "1.0.0",
  "source": "src/index.js",
  "main": "dist/main.js",
  "scripts": {
    "watch": "parcel watch",
    "build": "parcel build"
  },
  "devDependencies": {
    "parcel": "latest"
  }
}

现在你可以运行 yarn build 来构建要发布的项目，并运行 yarn watch 进行开发。

¥Now you can run yarn build to build your project for release and yarn watch in development.

CommonJS 和 ES 模块

¥CommonJS and ES modules

Parcel 接受 CommonJS 和 ES 模块作为输入，并且可以根据 package.json 中声明的内容输出其中一种或多种格式。要添加 ES 模块目标，请将 module 字段添加到 package.json。

¥Parcel accepts both CommonJS and ES modules as input, and can output one or more of these formats depending on what's declared in your package.json. To add an ES module target, add the module field to your package.json.

package.json:

{
  "name": "my-library",
  "version": "1.0.0",
  "source": "src/index.js",
  "main": "dist/main.js",
  "module": "dist/module.js",
  "devDependencies": {
    "parcel": "latest"
  }
}

现在 Parcel 将输出 dist/main.js 作为 CommonJS 模块，以及 dist/module.js 作为 ES 模块。使用你的库的工具将选择它们支持的其中一个。

¥Now Parcel will output dist/main.js as a CommonJS module, and dist/module.js as an ES module. Tools that consume your library will choose whichever of these they support.

你还可以使用文件扩展名来指示要输出的模块类型。.mjs 扩展将生成 ES 模块，.cjs 扩展将生成 CommonJS 模块。这会覆盖 main 字段的默认行为。还可以在 package.json 中设置 "type": "module" 字段，以将 main 字段也视为 ES 模块。有关详细信息，请参阅 Node.js 文档。

¥You can also use the file extension to indicate what type of module to output. The .mjs extension will produce an ES module, and the .cjs extension will produce a CommonJS module. This overrides the default behavior of the main field. The "type": "module" field can also be set in package.json to treat the main field as an ES module as well. See the Node.js docs for more details.

TypeScript

Parcel 还支持构建用 TypeScript 编写的库。source 字段可以指向你的入口 .ts 或 .tsx 文件，Parcel 会自动将 JavaScript 输出到你的目标中。你还可以使用 package.json 中的 types 字段指向 .d.ts 文件，Parcel 将在编译后的 JavaScript 旁边生成一个类型文件。这使得 VSCode 等编辑器可以为库的用户提供自动补齐功能。

¥Parcel also supports building libraries written in TypeScript. The source field can point to your entry .ts or .tsx file, and Parcel will output JavaScript into your targets automatically. You can also use the types field in package.json to point to a .d.ts file, and Parcel will generate a typings file alongside the compiled JavaScript. This lets editors like VSCode provide autocomplete for users of your library.

package.json:

{
  "name": "my-library",
  "version": "1.0.0",
  "source": "src/index.ts",
  "main": "dist/main.js",
  "module": "dist/module.js",
  "types": "dist/types.d.ts",
  "devDependencies": {
    "parcel": "latest"
  }
}

现在，除了编译的代码之外，Parcel 将输出一个 dist/types.d.ts 文件，其中包含我们库的类型定义。

¥Now Parcel will output a dist/types.d.ts file containing type definitions for our library in addition to the compiled code.

改进 Tree Shaking

¥Improving Tree Shaking

默认情况下，Parcel 将整个库打包到针对每个目标的单个文件中（例如 main 和 module）。如果你有许多可以独立使用的导出，则分发单独的文件可以改进最终应用中的 Tree Shaking。这可以使用 @parcel/bundler-library 插件完成。

¥By default, Parcel bundles your whole library into a single file for each target (e.g. main, and module). If you have many exports that may be used independently, distributing separate files can improve tree shaking in end applications. This can be done using the @parcel/bundler-library plugin.

.parcelrc:

{
  "extends": "@parcel/config-default",
  "bundler": "@parcel/bundler-library"
}

下一步

¥Next steps

现在你已经设置了项目，你可以了解 Parcel 的一些更高级的功能。查看有关目标的文档，并查看“秘诀”和“语言”部分，以获取使用流行 Web 框架和工具的更深入指南。

¥Now that you’ve set up your project, you're ready to learn about some more advanced features of Parcel. Check out the documentation about Targets, and see the Recipes and Languages sections for more in-depth guides using popular web frameworks and tools.