Parcel API

Parcel API 可用于以编程方式运行构建或监视项目的更改。它与 Parcel CLI 使用的 API 相同。当您需要更多灵活性或需要将 Parcel 集成到另一个构建系统中时，请使用此 API。

Parcel 构造函数

#

可以通过 @parcel/core 包使用 Parcel API。您还需要一个默认配置，如 @parcel/config-default。

yarn add @parcel/core @parcel/config-default

接下来，将此包导入您的程序并调用 Parcel 构造函数。它接受一个 InitialParcelOptions 对象，其中包含 Parcel CLI 使用的所有选项以及一些额外选项。

有两个必需参数：

build.mjs: 
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
  entries: "a.js",
  defaultConfig: "@parcel/config-default",
});

目标

#

默认情况下，Parcel 执行开发构建，但可以通过将 mode 选项设置为 production 来更改，这将启用作用域提升、压缩等。请参见生产。

您还可以使用 defaultTargetOptions 为未在项目中配置的目标设置值。例如，要覆盖默认浏览器目标，请使用 engines 选项。

build.mjs: 
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
  entries: "a.js",
  defaultConfig: "@parcel/config-default",
  mode: "production",
  defaultTargetOptions: {
    engines: {
      browsers: ["last 1 Chrome version"],
    },
  },
});

当设置为数组时，targets 选项可用于指定要构建的项目目标（如 package.json 中所述）。例如，仅构建项目的 modern 目标：

build.mjs: 
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
  entries: "a.js",
  defaultConfig: "@parcel/config-default",
  targets: ["modern"],
});

或者，targets 可以设置为对象，这将覆盖项目中定义的任何目标。有关可用选项的更多详细信息，请参见目标。

build.mjs: 
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
  entries: "a.js",
  defaultConfig: "@parcel/config-default",
  mode: "production",
  targets: {
    modern: {
      engines: {
        browsers: ["last 1 Chrome version"],
      },
    },
    legacy: {
      engines: {
        browsers: ["IE 11"],
      },
    },
  },
});

环境变量

#

可以使用 env 选项设置 NODE_ENV 等环境变量。这允许在不覆盖 process.env 上的值的情况下设置变量。

build.mjs: 
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
  entries: "a.js",
  defaultConfig: "@parcel/config-default",
  mode: "production",
  env: {
    NODE_ENV: "production",
  },
});

报告器

#

默认情况下，使用 API 时 Parcel 不会向 CLI 写入任何输出。这意味着它不会报告状态信息，也不会为诊断提供漂亮的格式。可以使用 additionalReporters 选项启用这些功能，该选项除了 .parcelrc 中指定的报告器外还会运行。@parcel/reporter-cli 插件提供 CLI 使用的默认报告器，但您也可以使用任何其他报告器插件。

build.mjs: 
import { Parcel } from "@parcel/core";
import { fileURLToPath } from "url";

let bundler = new Parcel({
  entries: "a.js",
  defaultConfig: "@parcel/config-default",
  additionalReporters: [
    {
      packageName: "@parcel/reporter-cli",
      resolveFrom: fileURLToPath(import.meta.url),
    },
  ],
});

构建

#

构造 Parcel 实例后，您可以使用它构建项目或监视更改。要构建一次，请使用 run API。这返回一个 Promise，如果构建成功，将使用包含 BundleGraph 和一些其他信息的 BuildSuccessEvent 进行解析，如果构建失败，则拒绝并出现错误。构建错误附加了一个或多个 Diagnostic 对象，其中包含出错的详细信息。

build.mjs: 
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
  entries: "a.js",
  defaultConfig: "@parcel/config-default",
});

try {
  let { bundleGraph, buildTime } = await bundler.run();
  let bundles = bundleGraph.getBundles();
  console.log(`✨ Built ${bundles.length} bundles in ${buildTime}ms!`);
} catch (err) {
  console.log(err.diagnostics);
}

监视

#

要监视项目的更改并在每次重新构建时收到通知，请使用 watch API。传递一个回调函数，在每次构建成功或失败时调用。回调接收一个错误参数和一个事件对象。错误参数仅用于监视期间的致命错误。正常的构建失败由 BuildFailureEvent 表示，其中包含 Diagnostic 对象列表。

watch 还返回一个订阅对象，当您想停止监视时，应调用 unsubscribe 方法。

build.mjs: 
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
  entries: "a.js",
  defaultConfig: "@parcel/config-default",
});

let subscription = await bundler.watch((err, event) => {
  if (err) {
    // 致命错误
    throw err;
  }

  if (event.type === "buildSuccess") {
    let bundles = event.bundleGraph.getBundles();
    console.log(`✨ Built ${bundles.length} bundles in ${event.buildTime}ms!`);
  } else if (event.type === "buildFailure") {
    console.log(event.diagnostics);
  }
});

// 一段时间后...
await subscription.unsubscribe();

开发服务器

#

开发服务器包含在默认的 Parcel 配置中。通过将 serveOptions 传递给 Parcel 构造函数并在监视模式下运行 Parcel 来启用它。通过设置 hmrOptions 可以启用热重载。port 是唯一必需的选项，但也可以设置 HTTPS 等其他选项。

build.mjs: 
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
  entries: "a.js",
  defaultConfig: "@parcel/config-default",
  serveOptions: {
    port: 3000,
  },
  hmrOptions: {
    port: 3000,
  },
});

文件系统

#

Parcel 在核心和大多数插件中使用抽象的文件系统。默认情况下，它依赖于 Node.js 的 fs API，但 Parcel 还有一个 MemoryFS 实现。您可以使用 inputFS 选项覆盖 Parcel 读取源文件的文件系统，并使用 outputFS 选项覆盖 Parcel 写入输出（包括缓存）的文件系统。

MemoryFS 位于 @parcel/fs 包中。构造它需要传递一个 WorkerFarm 实例，以便文件系统可以从多个线程读取和写入。您需要使用从 @parcel/core 导出的 createWorkerFarm 函数创建一个工作池，并将其传递给 MemoryFS 和 Parcel 构造函数。完成后，请确保在工作池上调用 end 以允许进程退出。

这个示例将其输出写入内存文件系统，并记录每个构建的捆绑包的内容。

build.mjs: 
import { Parcel, createWorkerFarm } from "@parcel/core";
import { MemoryFS } from "@parcel/fs";

let workerFarm = createWorkerFarm();
let outputFS = new MemoryFS(workerFarm);

let bundler = new Parcel({
  entries: "a.js",
  defaultConfig: "@parcel/config-default",
  workerFarm,
  outputFS,
});

try {
  let { bundleGraph } = await bundler.run();

  for (let bundle of bundleGraph.getBundles()) {
    console.log(bundle.filePath);
    console.log(await outputFS.readFile(bundle.filePath, "utf8"));
  }
} finally {
  await workerFarm.end();
}