リゾルバー

リゾルバープラグインは、依存関係の指定子を、トランスフォーマーによって処理される完全なファイルパスに変換する役割を担います。リゾルバーは、いずれかが結果を返すまでパイプラインで実行されます。デフォルトのリゾルバーがどのように機能するかについての詳細は、依存関係解決を参照してください。

例

この例では、special-moduleの解決をオーバーライドし、それ以外の場合はnullを返して、パイプライン内の次のリゾルバーが依存関係を処理できるようにします。この仕組みの詳細については、Parcel設定ドキュメントのリゾルバーを参照してください。

import {Resolver} from '@parcel/plugin';
import path from 'path';

export default new Resolver({
  async resolve({specifier}) {
    if (specifier === 'special-module') {
      return {
        filePath: path.join(__dirname, 'special-module.js')
      };
    }

    // Let the next resolver in the pipeline handle
    // this dependency.
    return null;
  }
});

設定の読み込み

ユーザーのプロジェクトから設定を読み込む場合は、ResolverプラグインのloadConfigメソッドで行う必要があります。この方法の詳細については、設定の読み込みを参照してください。

仮想モジュール

リゾルバーは、ファイルシステム上のファイルに解決するのではなく、codeを直接返すこともできます。これにより、必要に応じて仮想モジュールをプログラムで生成できます。ただし、コード内の依存関係を相対的に解決する場所や、トランスフォーマーがソースコードをどのように処理するか（たとえば、ファイル拡張子による）を示すため、filePathも返す必要があります。

import {Resolver} from '@parcel/plugin';
import path from 'path';

export default new Resolver({
  async resolve({specifier}) {
    if (specifier === 'special-module') {
      return {
        filePath: path.join(__dirname, 'special-module.js'),
        code: 'export default "This is a special module!";'
      };
    }

    return null;
  }
});

依存関係のメタデータ

specifierに加えて、Resolverプラグインは依存関係に関する追加のメタデータを含む完全なDependencyオブジェクトも受け取ります。specifierTypeプロパティは、specifierをどのように解釈する必要があるか（例：ESM、CommonJS、URLなど）を示します。resolveFromプロパティは、依存関係を解決する元のファイルパスを指定します（例：指定子が相対パスの場合）。

この例では、specifierTypeに応じて相対URLとパスを解決します。

import {Resolver} from '@parcel/plugin';
import path from 'path';
import {fileURLToPath, pathToFileURL} from 'url';

export default new Resolver({
  async resolve({specifier, dependency}) {
    return {
      filePath: dependency.specifierType === 'url'
        ? fileURLToPath(
          new URL(specifier, pathToFileURL(dependency.resolveFrom))
        )
        : path.resolve(dependency.resolveFrom, specifier)
    };
  }
});

モジュールの除外

isExcludedプロパティを返すことで、モジュールをビルドから除外する必要があることを示すことができます。この例では、AWSホスティング環境に自動的に含まれており、バンドルする必要のないaws-sdkを除外します。

import {Resolver} from '@parcel/plugin';

export default new Resolver({
  async resolve({specifier}) {
    if (specifier === 'aws-sdk') {
      return {isExcluded: true};
    }

    return null;
  }
});

キャッシュの無効化

Resolverプラグインの結果はParcelによって自動的にキャッシュされます。解決中にファイルシステムからファイルを読み取る場合は、それらを監視し、変更時に解決を無効化できるように、Parcelに通知する必要があります。

invalidateOnFileChangeプロパティは、解決中に正常に読み取られたすべてのファイルの配列に設定する必要があります。invalidateOnFileCreateプロパティは、作成された場合に解決を無効化するファイルを示すFileCreateInvalidationオブジェクトの配列に設定する必要があります。

import {Resolver} from '@parcel/plugin';
import path from 'path';

export default new Resolver({
  async resolve({specifier, options}) {
    let aliasFile = path.join(options.projectRoot, 'alias.json');

    try {
      let aliasConfig = await options.inputFS.readFile(aliasFile);
      let aliases = JSON.parse(aliasConfig);
      return {
        filePath: aliases[specifier] || null,
        invalidateOnFileChange: [aliasFile]
      };
    } catch (err) {
      return {
        invalidateOnFileCreate: [{filePath: aliasFile}]
      };
    }
  }
});

診断

Resolverプラグインは、解決中にエラーが発生する可能性があります。この場合、エラーをthrowするか、diagnosticsを返すことができます。リゾルバーがthrowすると、解決プロセスはすぐに停止し、エラーがユーザーに表示されます。

リゾルバーが代わりにdiagnosticsを返すと、解決は次のリゾルバープラグインに続行されます。どのリゾルバープラグインも依存関係を解決できない場合、すべてのリゾルバープラグインからのすべての診断がユーザーに表示されます。

import {Resolver} from '@parcel/plugin';
import path from 'path';

export default new Resolver({
  async resolve({specifier, options}) {
    let aliasFile = path.join(options.projectRoot, 'alias.json');

    try {
      let aliasConfig = await options.inputFS.readFile(aliasFile);
      let aliases = JSON.parse(aliasConfig);
      return {
        filePath: aliases[specifier] || null,
        invalidateOnFileChange: [aliasFile]
      };
    } catch (err) {
      return {
        invalidateOnFileCreate: [{filePath: aliasFile}],
        diagnostics: [
        {
          message: 'Could not read alias.json',
          hints: ['Create an alias.json file in the project root.']
        }]
      };
    }
  }
});

詳細については、診断を参照してください。

副作用

リゾルバーは、実行時にアセットに副作用があるかどうかを示すsideEffectsプロパティを返すこともできます。これは通常、package.jsonの同じプロパティに対応しており、スコープホイスティングに使用されます。

関連API

type ResolveResult = {|

  +filePath?: FilePath,

  +pipeline?: ?string,

  +query?: URLSearchParams,

  +isExcluded?: boolean,

  +priority?: DependencyPriority,

  +sideEffects?: boolean,

  +code?: string,

  +canDefer?: boolean,

  +diagnostics?: Diagnostic | Array<Diagnostic>,

  +meta?: JSONObject,

  +invalidateOnFileCreate?: Array<FileCreateInvalidation>,

  +invalidateOnFileChange?: Array<FilePath>,

  +invalidateOnEnvChange?: Array<string>,

|}

type Resolver<ConfigType> = {|

  loadConfig?: ({|
    config: Config,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Promise<ConfigType> | ConfigType,

  resolve({|
    dependency: Dependency,
    options: PluginOptions,
    logger: PluginLogger,
    specifier: FilePath,
    pipeline: ?string,
    config: ConfigType,
  |}): Async<?ResolveResult>,

|}