使用 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).
上面的示例使用 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.
现在,我们的库导出一个名为 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.
现在你可以运行 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
.
现在 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.
现在,除了编译的代码之外,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.
下一步
#¥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.