Transformer

A plugin type: Convert an asset (into another asset)

Transformers transform single assets as they are discovered and added to the asset graph. They mostly call out to different compilers and preprocessors.

import { Transform } from "@parcel/plugin";

export default new Transform({
  async canReuseAST({ ast, options, logger }) {
    return false;
  }

  async loadConfig({ config, options, logger }) {
    // ...
    return config;
  },

  async parse({ asset, config, logger, resolve, options }) {
    // ...
    return ast;
  },

  async transform({ asset, ast, config, logger, resolve, options }) {
    // ...
    return [asset];
  },

  async generate({ asset, ast, resolve, options }) {
    // ...
    return { code, map };
  },

  async postProcess({assets, config, options, resolve, logger}) {
    return assets;
  }
});

Relevant API

DependencyOptions website/generate-api-docs/example.flow:357

Usen when creating a Dependency, see that. 

type DependencyOptions = {|
  +moduleSpecifier: ModuleSpecifier,
  +isAsync?: boolean,
  +isEntry?: boolean,
  +isOptional?: boolean,
  +isURL?: boolean,
  +isWeak?: ?boolean,
  +loc?: SourceLocation,
  +env?: EnvironmentOpts,
  +meta?: Meta,
  +target?: Target,
  +symbols?: $ReadOnlyMap<CodeSymbol, {|
    local: CodeSymbol,
    loc: ?SourceLocation,
  |}>,
|}
Referenced by:
MutableAsset, TransformerResult

Dependency website/generate-api-docs/example.flow:396

A Dependency denotes a connection between two assets (likely some effect from the importee is expected - be it a side effect or a value is being imported). 

interface Dependency {
  +id: string,
  +moduleSpecifier: ModuleSpecifier,
  +isAsync: boolean,
  +isEntry: boolean,
  +isOptional: boolean,
  +isURL: boolean,
  +isWeak: ?boolean,
  +loc: ?SourceLocation,
  +env: Environment,
  +meta: Meta,
  +target: ?Target,
  +sourceAssetId: ?string,
  +sourcePath: ?string,
  +pipeline: ?string,
  +symbols: MutableCodeSymbols,
}
Referenced by:
ModuleSpecifier, DependencyOptions, BaseAsset, BundleTraversable, BundlerBundleGraphTraversable, MutableBundleGraph, BundleGraph, RuntimeAsset, Resolver, ResolvingProgressEvent

ASTGenerator website/generate-api-docs/example.flow:425 

type ASTGenerator = {|
  type: string,
  version: string,
|}
Referenced by:
BaseAsset

BaseAsset website/generate-api-docs/example.flow:446

An asset (usually represents one source file). 

interface BaseAsset {
  +env: Environment,
  +fs: FileSystem,
  +filePath: FilePath,
  +id: string,
  +meta: Meta,
  +isIsolated: boolean,
  +isInline: boolean,
  +isSplittable: ?boolean,
  +isSource: boolean,
  +type: string,
  +sideEffects: boolean,
  +uniqueKey: ?string,
  +astGenerator: ?ASTGenerator,
  +symbols: CodeSymbols,
  getAST(): Promise<?AST>,
Returns to current AST. See notes in subclasses (Asset, MutableAsset). 
  getCode(): Promise<string>,
Returns to current source code. See notes in MutableAsset. 
  getBuffer(): Promise<Buffer>,
Returns the contents as a buffer. 
  getStream(): Readable,
Returns the contents as a stream. 
  getMap(): Promise<?SourceMap>,
Returns the sourcemap (if existent). 
  getMapBuffer(): Promise<?Buffer>,
A buffer representation of the sourcemap (if existent). 
  getIncludedFiles(): $ReadOnlyArray<File>,
  getDependencies(): $ReadOnlyArray<Dependency>,
  getConfig(filePaths: Array<FilePath>, options: ?{|
    packageKey?: string,
    parse?: boolean,
  |}): Promise<ConfigResult | null>,
Used to load config files, (looks in every parent folder until a module root) for the specified filenames. packageKey can be used to also check pkg#[packageKey]. 
  getPackage(): Promise<PackageJSON | null>,
Returns the package.json this file belongs to. 
}
Referenced by:
MutableAsset, TransformerResult, ResolveResult

MutableAsset website/generate-api-docs/example.flow:496

A somewhat modifiable version of BaseAsset (for transformers) 

interface MutableAsset extends BaseAsset {
  isIsolated: boolean,
  isInline: boolean,
  isSplittable: ?boolean,
  type: string,
  addDependency(dep: DependencyOptions): string,
  addIncludedFile(file: File): void,
  addURLDependency(url: string, opts: $Shape<DependencyOptions>): string,
  +symbols: MutableCodeSymbols,
  isASTDirty(): boolean,
  getAST(): void,
Returns null if there is no AST. 
  setAST(AST): void,
  setBuffer(Buffer): void,
  setCode(string): void,
Throws if the AST is dirty (meaning: this won't implicity stringify the AST). 
  setEnvironment(opts: EnvironmentOpts): void,
  setMap(?SourceMap): void,
  setStream(Readable): void,
}
Referenced by:
BaseAsset, Transformer

Asset website/generate-api-docs/example.flow:523 

interface Asset extends BaseAsset {
  getAST(): void,
Throws if there is no AST. 
  +stats: Stats,
}
Referenced by:
BaseAsset, DedicatedThreadValidator, MultiThreadValidator, Transformer, BundleTraversable, BundlerBundleGraphTraversable, CreateBundleOpts, SymbolResolution, Bundle, MutableBundleGraph, BundleGraph, TransformingProgressEvent, BuildSuccessEvent

Config website/generate-api-docs/example.flow:534

FIXME 

interface Config {
  +isSource: boolean,
  +searchPath: FilePath,
  +result: ConfigResult,
  +env: Environment,
  +resolvedPath: ?FilePath,
  setResolvedPath(filePath: FilePath): void,
  setResult(result: ConfigResult): void,
  setResultHash(resultHash: string): void,
  addIncludedFile(filePath: FilePath): void,
  addDevDependency(name: PackageName, version?: Semver): void,
  setWatchGlob(glob: string): void,
  getConfigFrom(searchPath: FilePath, filePaths: Array<FilePath>, options: ?{|
    packageKey?: string,
    parse?: boolean,
    exclude?: boolean,
  |}): Promise<ConfigResult | null>,
  getConfig(filePaths: Array<FilePath>, options: ?{|
    packageKey?: string,
    parse?: boolean,
    exclude?: boolean,
  |}): Promise<ConfigResult | null>,
  getPackage(): Promise<PackageJSON | null>,
  shouldRehydrate(): void,
  shouldReload(): void,
  shouldInvalidateOnStartup(): void,
}
Referenced by:
Transformer

GenerateOutput website/generate-api-docs/example.flow:578 

type GenerateOutput = {|
  +content: Blob,
  +map?: ?SourceMap,
|}
Referenced by:
Transformer

TransformerResult website/generate-api-docs/example.flow:589

Will be used to generate a new BaseAsset, see that. 

type TransformerResult = {|
  +ast?: ?AST,
  +content?: ?Blob,
  +dependencies?: $ReadOnlyArray<DependencyOptions>,
  +env?: EnvironmentOpts,
  +filePath?: FilePath,
  +includedFiles?: $ReadOnlyArray<File>,
  +isInline?: boolean,
  +isIsolated?: boolean,
  +isSource?: boolean,
  +isSplittable?: boolean,
  +map?: ?SourceMap,
  +meta?: Meta,
  +pipeline?: ?string,
  +sideEffects?: boolean,
  +symbols?: $ReadOnlyMap<CodeSymbol, {|
    local: CodeSymbol,
    loc: ?SourceLocation,
  |}>,
  +symbolsConfident?: boolean,
  +type: string,
  +uniqueKey?: ?string,
|}
Referenced by:
Transformer

ResolveFn website/generate-api-docs/example.flow:618

Type
type ResolveFn = (from: FilePath, to: string) => Promise<FilePath>;
Referenced by:
Transformer

Transformer website/generate-api-docs/example.flow:682

The methods for a transformer plugin. 

type Transformer = {|
  getConfig?: ({|
    asset: MutableAsset,
    resolve: ResolveFn,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<ConfigResult | void>,
  loadConfig?: ({|
    config: Config,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<void>,
  preSerializeConfig?: ({|
    config: Config,
    options: PluginOptions,
  |}) => Async<void>,
  postDeserializeConfig?: ({|
    config: Config,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<void>,
  canReuseAST?: ({|
    ast: AST,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => boolean,
Whether an AST from a previous transformer can be reused (to prevent double-parsing) 
  parse?: ({|
    asset: MutableAsset,
    config: ?ConfigResult,
    resolve: ResolveFn,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<?AST>,
Parse the contents into an ast 
  transform({|
    asset: MutableAsset,
    config: ?ConfigResult,
    resolve: ResolveFn,
    options: PluginOptions,
    logger: PluginLogger,
  |}): Async<Array<TransformerResult | MutableAsset>>,
Transform the asset and/or add new assets 
  generate?: ({|
    asset: Asset,
    ast: AST,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<GenerateOutput>,
Stringify the AST 
  postProcess?: ({|
    assets: Array<MutableAsset>,
    config: ?ConfigResult,
    resolve: ResolveFn,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<Array<TransformerResult>>,
FIXME what is this even for? 
|}