Parcel API

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

Parcel 构造函数

#

Parcel API 可以通过 @parcel/core 包使用。您还需要一个默认配置，例如 @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，如果构建成功，该 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);
}

监视

#

要监视项目以进行更改并接收每个重建的通知，请使用 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) {
    // 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();

开发服务器

#

开发服务器包含在默认的 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
  }
});

await bundler.watch();

文件系统

#

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