bash
npm install esbuild
此命令应该会将 esbuild 安装到你本地的 node_modules 中。 你可以运行如下命令,来检测 esbuild 的原生可执行文件 是否正常:
bash
.\node_modules\.bin\esbuild --version
这是一个简易的真实案例,用于说明 esbuild 的能力以及如何使用它。 首先,请安装 react 和 react-dom 的 package:
bash
npm install react react-dom
bash
import * as React from 'react'
import * as Server from 'react-dom/server'
let Greet = () => <h1>Hello, world!</h1>
console.log(Server.renderToString(<Greet />))
最后,运行 esbuild 打包此文件:
bash
.\node_modules\.bin\esbuild app.jsx --bundle --outfile=out.js
不出意外的话,上述命令执行后会创建一个名为 out.js 的文件, 其中包含你的代码以及 React 库的代码。 代码完全独立,无需再依赖你的 node_modules。 如果你使用 node out.js 运行代码,你应该能看到如下内容:
js
<h1 data-reactroot="">Hello, world!</h1>
注意,esbuild 除了 jsx 扩展名, 无需任何配置就能够将 JSX 语法转换为 JavaScript。 尽管 esbuild 可以进行配置, 但它试图提供合理的默认值,以便在常见的情况下自动完成构建。 如果你想在 .js 文件中使用 JSX 语法,你可以通过设置 --loader:.js=jsx 选项, 来告诉 esbuild 对 js 文件进行 JSX 的编译。 更多关于可用配置项的说明,请参阅 API 文档。
在 package.json 中添加构建脚本, 具体代码如下:
js
{
"scripts": {
"build": "esbuild app.jsx --bundle --outfile=out.js"
}
}
js
require('esbuild').build({
entryPoints: ['app.jsx'],
bundle: true,
outfile: 'out.js',
}).catch(() => process.exit(1))
build 函数会在子进程中运行 esbuild 的可执行文件,并返回一个 Promise, 当构建完成后,该 Promise 将被 resolve。 上述代码并未打印捕获的异常, 因为异常中的任何错误信息默认会被打印到控制台(你 可以通过修改 日志级别 来按需关闭此功能)。
尽管有个同步的 buildSync API, 但异步 API 对于构建脚本来说更为合适, 因为插件只与异步 API 协同工作。 你可以在 API 文档 中了解更多关于构建 API 的配置项。
构建工具默认为浏览器输出代码, 所以无需额外配置就可以完成构建。 对于开发版本,你可能需要使用 --sourcemap 以启用 source map, 对于生产版本,你可能需要使用 --minify 启用压缩。 有时,你可能还需要为你支持的浏览器配置目标环境。 所以具体命令会像如下所示:
js
require('esbuild').buildSync({
entryPoints: ['app.jsx'],
bundle: true,
minify: true,
sourcemap: true,
target: ['chrome58', 'firefox57', 'safari11', 'edge16'],
outfile: 'out.js',
})
有时,你使用的包可能会引入另一个只能在 node 上运行的包, 例如 node 内置的 path 包。 当发生这种情况时,你可以通过在 package.json 中使用 browser 字段 来将此包替换成对浏览器友好的包,具体如下:
js
{
"browser": {
"path": "path-browserify"
}
}
有些你想使用的 npm 包可能并不是为在浏览器中运行设计的。 有时你可以使用 esbuild 的配置项来解决这些问题, 并成功打包。 未定义的全局变量在简单情况下可以用 define 功能代替, 如遇到更复杂的情况,可以用 inject 功能代替。