Parcel API

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

Parcel constructor

#

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

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

接下来,将此包导入您的程序并调用Parcel constructor。它接受一个InitialParcelOptions对象,该对象包含 Parcel CLI 使用的所有选项以及更多选项。

有两个必需参数:

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

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

目标 Targets

#

默认情况下,Parcel 进行开发构建,但这可以通过将mode选项设置为production,从而启用范围提升、缩小等。请参阅生产 Production

如果项目中未配置Targets,您还可以使用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可以设置为一个对象,该对象将覆盖项目中定义的任何目标。有关可用选项的更多详细信息,请参阅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"],
},
},
},
});

环境变量

#

环境变量如NODE_ENV可以使用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",
},
});

Reporters

#

默认情况下,当您使用该 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),
},
],
});

打包 Building

#

构建Parcel实例后,您可以使用它来构建项目或监视更改。要构建一次,请使用runAPI。这将返回一个 Promise,如果构建成功,它将通过BuildSuccessEvent包含BundleGraph和其他一些信息的信息来解决,或者如果构建失败,则以错误拒绝。构建错误有一个或多个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);
}

监听 Watching

#

要监视一个项目的更改并获得每次重建的通知,请使用watchAPI。每当生成成功或失败时,传递一个要调用的回调函数。回调接收一个错误参数和一个事件对象。Error 参数仅用于监视期间的致命错误。正常的构建失败由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) {
// fatal error
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);
}
});

// some time later...
await subscription.unsubscribe();

Dev server

#

开发服务器包含在默认的 Parcel 配置中。可以通过将serveOptions传递给Parcelconstructor 构造函数并在观看模式下运行 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,
},
});

await bundler.watch();

文件系统 File system

#

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

MemoryFS位于@parcel/fs包中。构造它需要传递一个WorkerFarm实例,以便可以从多个线程读取和写入文件系统。您需要使用从@parcel/core导出的createWorkerFarm函数创建一个工人农场,并将其传递给MemoryFSParcelconstructors构造函数。完成后,确保调用工作农场的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();
}