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コンストラクタを呼び出します。これは、Parcel CLIで使用されるすべてのオプションと、さらにいくつかのオプションを含むInitialParcelOptionsオブジェクトを受け入れます。
2つの必須パラメータがあります。
entries– ビルドするエントリポイントを記述する文字列または文字列の配列。 エントリを参照してください。configまたはdefaultConfig– 使用するParcel設定のファイルパスまたはパッケージ指定子。configが設定されている場合、指定された設定が常に使用され、プロジェクトの.parcelrcは無視されます。defaultConfigが設定されている場合、プロジェクトの.parcelrcが優先され、defaultConfigはフォールバックとして使用されます。相対パスまたはパッケージ指定子が指定されている場合、プロジェクトルートを基準に解決されます。
import {Parcel} from '@parcel/core';
let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default'
});ターゲット
#デフォルトでは、Parcelは開発ビルドを実行しますが、modeオプションをproductionに設定することで変更できます。これにより、スコープホーティング、ミニファイなどが有効になります。本番環境を参照してください。
プロジェクトで設定されていない場合、defaultTargetOptionsを使用してターゲットの値を設定することもできます。たとえば、デフォルトのブラウザターゲットを上書きするには、enginesオプションを使用します。
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ターゲットのみをビルドするには
import {Parcel} from '@parcel/core';
let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default',
targets: ['modern']
});あるいは、targetsをオブジェクトに設定して、プロジェクトで定義されているターゲットを上書きすることもできます。ターゲットで、使用可能なオプションの詳細を参照してください。
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の値を上書きせずに変数を設定できます。
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で使用されるデフォルトのレポーターを提供しますが、他のレポータープラグインを使用することもできます。
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インスタンスを構築したら、それを利用してプロジェクトをビルドしたり、変更を監視したりできます。一度ビルドするには、runAPIを使用します。これはPromiseを返し、ビルドが成功した場合はBundleGraphおよびその他の情報を含むBuildSuccessEventで解決され、失敗した場合はエラーで拒否されます。ビルドエラーには、何が間違っていたかの詳細を含む1つ以上のDiagnosticオブジェクトが添付されています。
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);
}監視
#プロジェクトの変更を監視し、各再ビルドを通知するには、watchAPIを使用します。ビルドが成功または失敗するたびに呼び出されるコールバックを渡します。コールバックは、エラーパラメータとイベントオブジェクトを受け取ります。エラーパラメータは、監視中の致命的なエラーに対してのみ使用されます。通常のビルドエラーは、Diagnosticオブジェクトのリストを含むBuildFailureEventで表されます。
watchはサブスクリプションオブジェクトも返し、監視を停止したい場合はunsubscribeメソッドを呼び出す必要があります。
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設定に含まれています。ParcelコンストラクタにserveOptionsを渡し、Parcelを監視モードで実行することで有効にできます。ホットリロードは、hmrOptionsを設定することで有効にできます。portは必須のオプションですが、HTTPSオプションなど、他のオプションを設定することもできます。
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のfsAPIに依存しますが、ParcelにはMemoryFS実装もあります。inputFSオプションを使用して、Parcelがソースファイルを読み取るファイルシステムを上書きし、outputFSオプションを使用して、Parcelが出力（キャッシュを含む）を書き込むファイルシステムを上書きできます。
MemoryFSは@parcel/fsパッケージにあります。構築するには、ファイルシステムを複数のスレッドから読み書きできるように、WorkerFarmインスタンスを渡す必要があります。@parcel/coreからエクスポートされるcreateWorkerFarm関数を使用してワーカーファームを作成し、MemoryFSとParcelコンストラクタの両方に渡す必要があります。完了したら、ワーカーファームでendを呼び出して、プロセスが終了できるようにします。
この例では、出力をメモリ内ファイルシステムに書き込み、ビルドされた各バンドルの内容をログに記録します。
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();
}