トランスフォーマー

トランスフォーマープラグインは、単一のアセットを変換してコンパイルしたり、依存関係を検出したり、異なる形式に変換したりします。多くのトランスフォーマーは、コンパイラーやプリプロセッサーなどの他のツールのラッパーであり、それらをParcelと統合する役割を担っています。

アセットの変換

Transformerコンストラクターに渡す必要のある必須関数が1つあります。それがtransformです。この関数は、ファイルを表すMutableAssetオブジェクトを受け取ります。アセットのソースコードまたはコンテンツは、関連するソースマップ（下記参照）とともに取得できます。トランスフォーマーは、このコンテンツを何らかの方法で変換し、コンパイルされた結果をアセットに設定できます。

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

export default new Transformer({
  async transform({asset}) {
    // Retrieve the asset's source code and source map.
    let source = await asset.getCode();
    let sourceMap = await asset.getMap();

    // Run it through some compiler, and set the results 
    // on the asset.
    let {code, map} = compile(source, sourceMap);
    asset.setCode(code);
    asset.setMap(map);

    // Return the asset
    return [asset];
  }
});

設定の読み込み

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

アセットタイプの変更

トランスフォーマーは、アセットをある形式から別の形式に変換できます。たとえば、TypeScriptからJavaScriptに変換できます。これを行うには、アセットのtypeプロパティを新しいファイルタイプ（例：js）に設定します。その後、アセットは新しいタイプに一致するパイプラインによって処理されます。詳細については、Parcel設定ドキュメントのトランスフォーマーを参照してください。

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

export default new Transformer({
  async transform({asset}) {
    let code = await asset.getCode();

    let result = compile(code);
    asset.type = 'js';
    asset.setCode(result);

    return [asset];
  }
});

環境

アセットは、アセットをどのようにコンパイルする必要があるかを記述するEnvironmentに関連付けられています。同じアセットが、最新のターゲットとレガシーターゲットのビルドなど、異なる環境で複数回処理される場合があります。可能であれば、トランスフォーマープラグインは、結果がターゲットで動作し、最適化されるように、コードをコンパイルするときに環境を考慮する必要があります。詳細については、ターゲットを参照してください。

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

export default new Transformer({
  async transform({asset}) {
    let code = await asset.getCode();

    let result = asset.env.isBrowser()
      ? compileForBrowser(code, asset.engines.browser)
      : compileForNode(code, asset.engines.node);

    asset.setCode(result);
    return [asset];
  }
});

利用可能なプロパティの詳細については、Environment APIドキュメントを参照してください。

依存関係の追加

アセットのコンテンツを変換することに加えて、トランスフォーマープラグインは、Parcelによって処理される可能性のあるコード内の依存関係を検出する役割も担っています。一部のトランスフォーマーは、別のトランスフォーマーが後で実行してそれを行うため（たとえば、デフォルトのJavaScriptトランスフォーマー）、この点を気にする必要はありません。Parcelでサポートされている既存の言語のいずれにもコンパイルされない新しい言語のサポートを追加する場合、またはコンパイルされたコードの外部に依存関係を導入する場合は、それらをアセットに追加する必要があります。

依存関係は、DependencyOptionsオブジェクトを渡すaddDependencyメソッドを使用してアセットに追加できます。必須パラメーターは2つあります。依存関係の場所を記述する文字列であるspecifierと、指定子をどのように解釈する必要があるかを記述するspecifierTypeです。詳細については、依存関係解決を参照してください。

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

export default new Transformer({
  async transform({asset}) {
    let code = await asset.getCode();
    let deps = code.matchAll(/import "(.*?)"/g);
    
    for (let dep of deps) {
      asset.addDependency({
        specifier: dep,
        specifierType: 'esm'
      });
    }

    return [asset];
  }
});

バンドルへの影響

依存関係が指定される方法は、それがどのようにバンドルされるかに影響を与える可能性があります。デフォルトでは、依存関係は同じ出力ファイルにまとめてバンドルされます。依存関係のpriorityプロパティは、依存しているアセットと並行して、または遅延ロードする必要があることを指定できます。たとえば、JavaScriptの動的なimport()は、lazy優先度で依存関係をロードします。詳細については、コード分割を参照してください。

bundleBehaviorプロパティは、依存関係がどのようにバンドルされるかをさらに制御します。たとえば、bundleBehaviorをinlineに設定することで、依存関係を新しいバンドルに分離できますが、親にインライン化できます。詳細については、バンドルインライン化を参照してください。

利用可能な各オプションの詳細については、DependencyOptionsを参照してください。

URL依存関係

一部の言語では、依存関係はURLで他のファイルを参照します。コンパイルされたコードでは、これらのURL参照を更新して、最終的なバンドル名を指すようにする必要があります。ただし、アセットが変換されている場合、バンドル名はまだわかっていません。

addDependencyは一意の依存関係IDを返します。これは、最終的なバンドルURLのプレースホルダーとして変換されたアセットコンテンツに配置でき、URLがわかると、後でパケージャーによって置き換えられます。

ショートカットとして、addURLDependencyメソッドは、specifierTypeがurlに設定され、priorityがlazyに設定された（別のバンドルを作成する）依存関係を作成します。

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

export default new Transformer({
  async transform({asset}) {
    let code = await asset.getCode();
    let result = code.replace(/import "(.*?)"/g, (m, dep) => {
      // Replace the original specifier with a dependency id 
      // as a placeholder. This will be replaced later with 
      // the final bundle URL.
      let depId = asset.addURLDependency(dep);
      return `import "${depId}"`;
    });

    asset.setCode(result);
    return [asset];
  }
});

ASTの再利用

複数のトランスフォーマープラグインがアセットに対して連続して実行される場合、同じ解析済みASTを再利用できる場合は、各トランスフォーマーに対して解析、変換、およびコード生成を行うのは無駄です。Parcelは、transform関数をいくつかの部分に分割することで、ASTの共有を容易にします。

• canReuseAST – 以前のトランスフォーマープラグインからASTが利用可能な場合は、利用可能な場合、次のトランスフォーマーのこのメソッドに渡されます。ASTのtypeとversionを調べて、再利用できるかどうかを判断する必要があります。trueを返した場合、parseメソッドは呼び出されず、ASTが再利用されます。falseを返した場合、以前のトランスフォーマーのgenerate関数が呼び出され、次のトランスフォーマーのparse関数が結果とともに呼び出されます。
• parse – ASTが利用できない場合、またはcanReuseASTがfalseを返した場合、トランスフォーマーのparse関数が呼び出されます。ASTのタイプ、バージョン、およびコンテンツを記述するASTオブジェクトを返す必要があります。
• generate – 次のトランスフォーマーがASTを再利用できない場合、またはこれがパイプラインの最後のトランスフォーマーである場合、ASTオブジェクトとともにgenerateが呼び出されます。生成されたコンテンツとソースマップを含む結果オブジェクトが返される必要があります。

import {Transformer} from '@parcel/plugin';
import semver from 'semver';

export default new Transformer({
  async canReuseAST({ast}) {
    return ast.type === 'my-compiler' 
      && semver.satisfies(ast.version, '^1.0.0');
  },
  async parse({asset}) {
    return {
      type: 'my-compiler',
      version: '1.0.0',
      program: parse(await asset.getCode())
    };
  },
  async transform({asset}) {
    let ast = await asset.getAST();

    let compiledAST = compile(ast.program);
    asset.setAST({
      type: 'my-compiler',
      version: '1.0.0',
      program: compiledAST
    });

    return [asset];
  },
  async generate({ast}) {
    let {content, map} = generate(ast.program);
    return {
      content,
      map
    };
  }
});

ソースマップ

ソースマップは、コンパイルされたコードとバンドルされたコードの場所を元のソースコードにマッピングすることにより、ブラウザーでコンパイルされたコードをデバッグする際に開発者を支援します。トランスフォーマープラグインは、可能であれば、コンテンツを変換するときにソースマップをアセットに追加する必要があります。アセットは複数のトランスフォーマーによって処理される可能性があるため、コンテンツに加えて、アセットに含まれる既存のソースマップも変換する必要があります。

Parcelは、ソースマップ操作に@parcel/source-mapライブラリを使用します。使用方法の詳細については、ソースマップを参照してください。他のツールとの間で受け渡しするソースマップを変換する必要がある場合があります。

import {Transformer} from '@parcel/plugin';
import SourceMap from '@parcel/source-map';

export default new Transformer({
  async transform({asset, options}) {
    let source = await asset.getCode();
    let sourceMap = await asset.getMap();

    // Convert the input source map to JSON.
    let result = compile(source, sourceMap.toVLQ());
    asset.setCode(result.code);

    // Convert returned JSON source map to a Parcel SourceMap.
    let map = new SourceMap(options.projectRoot);
    map.addVLQMap(result.map);
    asset.setMap(map);

    return [asset];
  }
});

バイナリデータ

トランスフォーマーは、テキスト形式のソースコードに加えて、バイナリコンテンツも処理できます。これは、Bufferを使用するか、ストリームを使用することによって行うことができます。

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

export default new Transformer({
  async transform({asset}) {
    let buffer = await asset.getBuffer();

    let result = transform(buffer);
    asset.setBuffer(result);

    return [asset];
  }
});

クエリパラメーター

アセットは、クエリパラメーター付きの依存関係によって参照される場合があります。これらは、アセットのコンパイルまたは変換時にトランスフォーマーが使用するオプションを指定します。たとえば、Parcelの画像トランスフォーマーは、クエリパラメーターを使用して、ユーザーが画像を変換する幅、高さ、形式を指定できるようにします。同じアセットを、異なるクエリパラメーターを使用して複数回コンパイルできます。

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

export default new Transformer({
  async transform({asset}) {
    let buffer = await asset.getBuffer();

    let result = resize(
      buffer,
      asset.query.width,
      asset.query.height
    );

    asset.setBuffer(result);
    return [asset];
  }
});

複数のアセットの返却

ここまでのすべての例では、単一のアセットを変換する方法を示しました。ただし、場合によっては、1つのファイルに複数の異なるアセットが含まれる場合があります。たとえば、HTMLには、独自の個別のParcelパイプラインを介して処理する必要のあるインラインの<script>および<style>要素があります。このため、Parcelでは、トランスフォーマーから複数のアセットを返すことができます。

新しいアセットを作成するには、TransformerResult オブジェクトの配列を返します。これらのオブジェクトは type と content を持つ必要がありますが、自身に依存関係を持たせたり、Asset オブジェクトと同じオプションを多く持たせたりすることもできます。

通常、元のアセットに加えて、それが持つ可能性のあるすべての子アセットを返す必要があります。親は、子アセットに uniqueKey プロパティを割り当て、それを依存関係の specifier として参照することで、子アセットに対する依存関係を作成できます。これにより、ファイルシステムには実際には存在しないが、存在するかのように参照できる「仮想」アセットを作成できます。

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

export default new Transformer({
  async transform({asset}) {
    let code = await asset.getCode();

    // Extract inline assets to return in addition to this asset.
    let assets = [asset];

    let uniqueKey = `${asset.id}-style`;
    assets.push({
      type: 'css',
      content: '...',
      uniqueKey,
      bundleBehavior: 'inline'
    });

    // Add a dependency, using the uniqueKey as a specifier.
    asset.addDependency({
      specifier: uniqueKey,
      specifierType: 'esm'
    });

    return assets;
  }
});

関連するAPI

type DependencyOptions = {|

  +specifier: DependencySpecifier,

  +specifierType: SpecifierType,

  +priority?: DependencyPriority,

  +bundleBehavior?: BundleBehavior,

  +needsStableName?: boolean,

  +isOptional?: boolean,

  +loc?: SourceLocation,

  +env?: EnvironmentOptions,

  +packageConditions?: Array<string>,

  +meta?: Meta,

  +pipeline?: string,

  +resolveFrom?: FilePath,

  +range?: SemverRange,

  +symbols?: $ReadOnlyMap<Symbol, {|
    local: Symbol,
    loc: ?SourceLocation,
    isWeak: boolean,
    meta?: Meta,
  |}>,

|}

interface Dependency {

  +id: string,

  +specifier: DependencySpecifier,

  +specifierType: SpecifierType,

  +priority: DependencyPriority,

  +bundleBehavior: ?BundleBehavior,

  +needsStableName: boolean,

  +isOptional: boolean,

  +isEntry: boolean,

  +loc: ?SourceLocation,

  +env: Environment,

  +packageConditions: ?Array<string>,

  +meta: Meta,

  +target: ?Target,

  +sourceAssetId: ?string,

  +sourcePath: ?FilePath,

  +sourceAssetType: ?string,

  +resolveFrom: ?FilePath,

  +range: ?SemverRange,

  +pipeline: ?string,

  +symbols: MutableDependencySymbols,

}

type ASTGenerator = {|

  type: string,

  version: Semver,

|}

interface BaseAsset {

  +id: string,

  +fs: FileSystem,

  +filePath: FilePath,

  +type: string,

  +query: URLSearchParams,

  +env: Environment,

  +isSource: boolean,

  +meta: Meta,

  +bundleBehavior: ?BundleBehavior,

  +isBundleSplittable: boolean,

  +sideEffects: boolean,

  +uniqueKey: ?string,

  +astGenerator: ?ASTGenerator,

  +pipeline: ?string,

  +symbols: AssetSymbols,

  getAST(): Promise<?AST>,

  getCode(): Promise<string>,

  getBuffer(): Promise<Buffer>,

  getStream(): Readable,

  getMap(): Promise<?SourceMap>,

  getMapBuffer(): Promise<?Buffer>,

  getDependencies(): $ReadOnlyArray<Dependency>,

}

interface MutableAsset extends BaseAsset {

  type: string,

  bundleBehavior: ?BundleBehavior,

  isBundleSplittable: boolean,

  sideEffects: boolean,

  +symbols: MutableAssetSymbols,

  addDependency(DependencyOptions): string,

  addURLDependency(url: string, opts: $Shape<DependencyOptions>): string,

  invalidateOnFileChange(FilePath): void,

  invalidateOnFileCreate(FileCreateInvalidation): void,

  invalidateOnEnvChange(string): void,

  setCode(string): void,

  setBuffer(Buffer): void,

  setStream(Readable): void,

  setAST(AST): void,

  isASTDirty(): boolean,

  setMap(?SourceMap): void,

  setEnvironment(opts: EnvironmentOptions): void,

}

interface Asset extends BaseAsset {

  +stats: Stats,

}

interface Config {

  +isSource: boolean,

  +searchPath: FilePath,

  +env: Environment,

  invalidateOnFileChange(FilePath): void,

  invalidateOnFileCreate(FileCreateInvalidation): void,

  invalidateOnEnvChange(string): void,

  invalidateOnStartup(): void,

  invalidateOnBuild(): void,

  addDevDependency(DevDepOptions): void,

  setCacheKey(string): void,

  getConfig<T>(filePaths: Array<FilePath>, options?: {|
    packageKey?: string,
    parse?: boolean,
    exclude?: boolean,
  |}): Promise<?ConfigResultWithFilePath<T>>,

  getConfigFrom<T>(searchPath: FilePath, filePaths: Array<FilePath>, options?: {|
    packageKey?: string,
    parse?: boolean,
    exclude?: boolean,
  |}): Promise<?ConfigResultWithFilePath<T>>,

  getPackage(): Promise<?PackageJSON>,

}

type GenerateOutput = {|

  +content: Blob,

  +map?: ?SourceMap,

|}

type TransformerResult = {|

  +type: string,

  +content?: ?Blob,

  +ast?: ?AST,

  +map?: ?SourceMap,

  +dependencies?: $ReadOnlyArray<DependencyOptions>,

  +env?: EnvironmentOptions | Environment,

  +bundleBehavior?: ?BundleBehavior,

  +isBundleSplittable?: boolean,

  +meta?: Meta,

  +pipeline?: ?string,

  +sideEffects?: boolean,

  +symbols?: $ReadOnlyMap<Symbol, {|
    local: Symbol,
    loc: ?SourceLocation,
  |}>,

  +uniqueKey?: ?string,

|}

type ResolveOptions = {|

  +specifierType?: SpecifierType,

  +packageConditions?: Array<string>,

|}

type ResolveFn = (from: FilePath, to: string, options?: ResolveOptions) => Promise<FilePath>;

type Transformer<ConfigType> = {|

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

  canReuseAST?: ({|
    ast: AST,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => boolean,

  parse?: ({|
    asset: Asset,
    config: ConfigType,
    resolve: ResolveFn,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<?AST>,

  transform({|
    asset: MutableAsset,
    config: ConfigType,
    resolve: ResolveFn,
    options: PluginOptions,
    logger: PluginLogger,
  |}): Async<Array<TransformerResult | MutableAsset>>,

  postProcess?: ({|
    assets: Array<MutableAsset>,
    config: ConfigType,
    resolve: ResolveFn,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<Array<TransformerResult>>,

  generate?: ({|
    asset: Asset,
    ast: AST,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<GenerateOutput>,

|}