📚 API

Bundler

你可以选择使用 API 替代 CLI 来初始化 bunlder 对象,以获取更高级的使用方式(例如:在每次构建时进行自定义操作)。 针对每个选项都给出了可参考的示例进行解释说明:

const Bundler = require('parcel-bundler');
const Path = require('path');

// 入口文件路径
const file = Path.join(__dirname, './index.html');

// Bundler 选项
const options = {
  outDir: './dist', // 将生成的文件放入输出目录下,默认为 dist
  outFile: 'index.html', // 输出文件的名称
  publicUrl: './', // 静态资源的 url ,默认为 dist
  watch: true, // 是否需要监听文件并在发生改变时重新编译它们,默认为 process.env.NODE_ENV !== 'production'
  cache: true, // 启用或禁用缓存,默认为 true
  cacheDir: '.cache', // 存放缓存的目录,默认为 .cache
  contentHash: false, // 禁止将内容的 hash 值包含在文件名中
  minify: false, // 压缩文件,当 process.env.NODE_ENV === 'production' 时启用压缩
  scopeHoist: false, // 开启实验性的 scope hoisting/tree shaking 特性,能够产出更小的生产环境包
  target: 'browser', // 可选的目标平台:browser/node/electron,默认为 browser
  https: false, // 服务器文件使用 https 或者 http,默认为 false
  logLevel: 3, // 3 = 输出所有内容, 2 = 输出警告和错误, 1 = 输出错误
  hmrPort: 0, // hmr socket 运行的端口,默认为随机空闲端口(在 Node.js 中,0 会被解析为随机空闲端口)
  sourceMaps: true, // 启用或禁用 sourcemaps,默认为启用(在精简版本中不支持)
  hmrHostname: '', // 热模块重载的主机名,默认为 ''
  detailedReport: false // 打印 bundles、资源、文件大小和使用时间的详细报告,默认为 false,只有在禁用监听状态时才打印报告
};

async function runBundle() {
  // 使用提供的入口文件路径和参数初始化 bundler
  const bundler = new Bundler(file, options);

  // 运行 bundler,这将返回主 bundle 对象
  // 如果你正在使用监听模式,请使用下面这些事件,这是因为该 promise 只会触发一次,而不是每次重新构建时都触发
  const bundle = await bundler.bundle();
}

runBundle();

事件

这是所有的 bundler 事件列表。

Bundle

Bundle 是 Parcel 用来将资源打包在一起的工具,它还包含能够构建出 bundle 树的子 bundle 和兄弟 bundle。

属性

Bundle 包含一个 parentBundlechildBundlessiblingBundles,所有这些属性一起创建一个快速迭代的 bundle 树。

资源树及其生成的 bundle 树的基本示例如下:

资源树:

index.html 引用 index.jsindex.css

index.js 引用 test.jstest.txt

index.html
-- index.js
 |--- test.js
 |--- test.txt
-- index.css
Bundle 树:

index.html 被作为主 bundle 的入口资源,这个主 bundle 创建了两个子 bundle ,一个用于 index.js,另一个用于 index.css ,这是因为它们与 html 的类型不同。

index.js 引入了两个文件,test.jstest.txt

test.js 被添加到了 index.js bundle 的资源中,因为它与 index.js 的类型相同。

test.txt 会创建一个新的 bundle,并被添加到 index.js bundle 的子元素中,因为它是与 index.js 不同的资源类型。

index.css 没有引用资源,因此只包含它的入口资源。

index.cssindex.js 这两个 bundle 为共享同一父 bundle 的兄弟 bundle(siblingBundles)。

index.html
-- index.js (includes index.js and test.js)
 |--- test.txt (includes test.txt)
-- index.css (includes index.css)

中间件(Middleware)

中间件可以用于 hook 到 http 服务中(例如:express 或者 Node.js http) 。

在 express 中使用 parcel 中间件的实例

const Bundler = require('parcel-bundler');
const app = require('express')();

const file = 'index.html'; // Pass an absolute path to the entrypoint here
const options = {}; // See options section of api docs, for the possibilities

// 使用 file 和 options 参数,初始化新的 bundler
const bundler = new Bundler(file, options);

// 让 express 使用 bundler 中间件,这将让 parcel 处理你 express 服务器上的每个请求
app.use(bundler.middleware());

// Listen on port 8080
app.listen(8080);