Parcel API

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

¥The Parcel API can be used to programmatically run builds or watch a project for changes. It is the same API as is used by the Parcel CLI. Use the API when you need more flexibility, or need to integrate Parcel into another build system.

`Parcel` 构造函数

¥The Parcel constructor

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

¥The Parcel API can be used through the @parcel/core package. You'll also need a default configuration, such as @parcel/config-default.

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

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

¥Next, import this package into your program and call the Parcel constructor. It accepts an InitialParcelOptions object, which contains all of the options used by the Parcel CLI and a few more.

有两个必需参数：

¥There are two required parameters:

entries - 描述要构建的入口点的字符串或字符串数组。参见入口。

¥entries – A string or an array of strings describing the entry points to build. See Entries.
config 或 defaultConfig – 供 Parcel 配置使用的文件路径或包说明符。如果设置了 config，则始终使用提供的配置并忽略项目 .parcelrc。如果设置了 defaultConfig，则项目的 .parcelrc 优先，defaultConfig 用作后备。如果给出了相对路径或包说明符，则会相对于项目根目录进行解析。

¥config or defaultConfig – A file path or package specifier for a Parcel config to use. If config is set, the provided config is always used and the project .parcelrc is ignored. If defaultConfig is set, the project's .parcelrc takes precedence, and defaultConfig is used as a fallback. If a relative path or package specifier is given, it is resolved relative to the project root.

build.mjs:

import {Parcel} from '@parcel/core';

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

目标

¥Targets

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

¥By default, Parcel does a development build, but this can be changed by setting the mode option to production, which enable scope hoisting, minification, etc. See Production.

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

¥You can also use the defaultTargetOptions to set values for Targets if they aren't configured in the project. For example, to override the default browser targets, use the engines option.

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 目标：

¥When set to an array, the targets option can be used to specify which of the project’s targets (as described in package.json) to build. For example, to only build the project’s modern target:

build.mjs:

import {Parcel} from '@parcel/core';

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

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

¥Alternatively, targets may be set to an object, which will override any targets defined in the project. See Targets for more details on the available options.

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']
      }
    }
  }
});

环境变量

¥Environment variables

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

¥Environment variables such as NODE_ENV may be set using the env option. This allows variables to be set without overriding the values on 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 使用的默认报告器，但你也可以使用任何其他报告器插件。

¥By default, Parcel does not write any output to the CLI when you use the API. That means it won’t report status information, and provides no pretty formatting for diagnostics. These can be enabled using the additionalReporters option, which run in addition to any reporters specified in .parcelrc. The @parcel/reporter-cli plugin provides the default reporter used by the CLI, but you can use any other reporter plugins as well.

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 实例，你就可以使用它来构建项目或监视更改。要构建一次，请使用 run API。这将返回一个 Promise，如果构建成功，则将使用包含 BundleGraph 和其他一些信息的 BuildSuccessEvent 来解决该 Promise，如果失败，则将拒绝并返回错误。构建错误会附加一个或多个 Diagnostic 对象，其中包含错误的详细信息。

¥Once you’ve constructed a Parcel instance, you can use it to build a project or watch for changes. To build once, use the run API. This returns a Promise, which will be resolved with a BuildSuccessEvent containing the BundleGraph and some other information if the build was successful, or reject with an error if it failed. Build errors have one or more Diagnostic objects attached to them with the details of what went wrong.

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

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

¥To watch a project for changes and be notified of each rebuild, use the watch API. Pass a callback to be called whenever a build succeeds or fails. The callback receives an error parameter and an event object. The error parameter is only used for fatal errors during watching. Normal build failures are represented by a BuildFailureEvent, which includes a list of Diagnostic objects.

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

¥watch also returns a subscription object, and you should call the unsubscribe method when you’d like to stop watching.

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 传递给 Parcel 构造函数并在监视模式下运行 Parcel 来启用它。可以通过设置 hmrOptions 来启用热重载。port 是唯一必需的选项，但也可以设置其他选项，例如 HTTPS 选项。

¥The development server is included in the default Parcel config. It can be enabled by passing serveOptions to the Parcel constructor and running Parcel in watch mode. Hot reloading can be enabled by setting hmrOptions. A port is the only required option, but others such as HTTPS options may also be set.

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 fs API，但 Parcel 也有 MemoryFS 实现。你可以使用 inputFS 选项覆盖 Parcel 从中读取源文件的文件系统，并使用 outputFS 选项覆盖 Parcel 写入输出（包括缓存）的文件系统。

¥Parcel uses an abstracted file system throughout core and in most plugins. By default, it relies on the Node.js fs API, but Parcel also has a MemoryFS implementation. You can use the inputFS option to override the file system Parcel reads source files from, and the outputFS option to override the file system Parcel writes output (including the cache) to.

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

¥The MemoryFS is located in the @parcel/fs package. Constructing it requires passing a WorkerFarm instance so that the file system can be read and written to from multiple threads. You’ll need to create a worker farm using the createWorkerFarm function exported from @parcel/core, and pass this to both the MemoryFS and Parcel constructors. When you are done, make sure to call end on the worker farm to allow the process to exit.

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

¥This example writes its output into an in-memory file system, and logs the contents of each built bundle.

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();
}

Parcel 构造函数

目标

环境变量

报告器

架构

监视

开发服务器

文件系统

`Parcel` 构造函数