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 { Transformer } from "@parcel/plugin";

export default new Transformer({
  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 parcel/packages/core/types/index.js:368

Usen when creating a Dependency, see that. 

type DependencyOptions = {|
  +moduleSpecifier: ModuleSpecifier,
  +isAsync?: boolean,
  +isEntry?: boolean,
Is merged with the environment of the importer 
  +isOptional?: boolean,
  +isURL?: boolean,
  +isWeak?: ?boolean,
  +isIsolated?: boolean,
  +loc?: SourceLocation,
  +env?: EnvironmentOpts,
  +meta?: Meta,
  +target?: Target,
  +symbols?: $ReadOnlyMap<Symbol, {|
    local: Symbol,
    loc: ?SourceLocation,
  |}>,
|}
Referenced by:
MutableAsset, TransformerResult

Dependency parcel/packages/core/types/index.js:390

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,
E.g. "lodash" in import {add} from "lodash"; 
  +isAsync: boolean,
  +isEntry: ?boolean,
Whether this should become a entry in a bundle. 
  +isOptional: boolean,
Whether a failed resolution should not cause a build error. 
  +isURL: boolean,
Whether an URL is expected (rather than the language-specific behaviour). 
  +isWeak: ?boolean,
Whether this dependency does not provide any values for the importer itself. 
  +isIsolated: boolean,
  +loc: ?SourceLocation,
Used for error messages, the code location that caused this dependency. 
  +env: Environment,
  +meta: Meta,
  +target: ?Target,
  +sourceAssetId: ?string,
Used for error messages, the importer. 
  +sourcePath: ?string,
Used for error messages, the importer. 
  +pipeline: ?string,
a named pipeline (if the moduleSpecifier didn't specify one). 
  +symbols: MutableSymbols,
}
Referenced by:
BaseAsset, BundleGraph, BundleTraversable, BundlerBundleGraphTraversable, DependencyOptions, ModuleSpecifier, MutableBundleGraph, Resolver, ResolvingProgressEvent, RuntimeAsset

ASTGenerator parcel/packages/core/types/index.js:429 

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

BaseAsset parcel/packages/core/types/index.js:439

An asset (usually represents one source file). 

interface BaseAsset {
  +env: Environment,
  +fs: FileSystem,
The file system where the source is located. 
  +filePath: FilePath,
  +query: QueryParameters,
  +id: string,
  +meta: Meta,
  +isIsolated: boolean,
  +isInline: boolean,
Whether this asset will/should later be inserted back into the importer. 
  +isSplittable: ?boolean,
  +isSource: boolean,
Whether this is asset is part of the users project (and not of an external dependencies) and should be transpiled. 
  +type: string,
Usually corresponds to the file extension 
  +sideEffects: boolean,
Whether this asset can be omitted if none if it's exports are being used (set by ResolveResult) 
  +uniqueKey: ?string,
Inline assets inheirit the parent's id, making it not be enough for a unique identification (this could be a counter that is unique per asset) 
  +astGenerator: ?ASTGenerator,
The type of the AST. 
  +pipeline: ?string,
  +symbols: Symbols,
a Map<export name, name of binding> 
  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). 
  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:
Asset, MutableAsset, ResolveResult, TransformerResult

MutableAsset parcel/packages/core/types/index.js:500

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(filePath: FilePath): void,
  addURLDependency(url: string, opts: $Shape<DependencyOptions>): string,
  invalidateOnEnvChange(env: string): void,
  +symbols: MutableSymbols,
  isASTDirty(): boolean,
  getAST(): Promise<?AST>,
Returns null if there is no AST. 
  setAST(AST): void,
  setBuffer(Buffer): void,
  setCode(string): void,
  getCode(): Promise<string>,
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 parcel/packages/core/types/index.js:529 

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

Config parcel/packages/core/types/index.js:539 

interface Config {
  +isSource: boolean,
  +searchPath: FilePath,
  +result: ConfigResult,
  +env: Environment,
  +includedFiles: Set<FilePath>,
  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<ConfigResultWithFilePath | null>,
  getConfig(filePaths: Array<FilePath>, options: ?{|
    packageKey?: string,
    parse?: boolean,
    exclude?: boolean,
  |}): Promise<ConfigResultWithFilePath | null>,
  getPackage(): Promise<PackageJSON | null>,
  shouldRehydrate(): void,
  shouldReload(): void,
  shouldInvalidateOnStartup(): void,
}
Referenced by:
Transformer

GenerateOutput parcel/packages/core/types/index.js:582 

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

TransformerResult parcel/packages/core/types/index.js:593

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<Symbol, {|
    local: Symbol,
    loc: ?SourceLocation,
  |}>,
  +symbolsConfident?: boolean,
  +type: string,
  +uniqueKey?: ?string,
|}
Referenced by:
Transformer

ResolveFn parcel/packages/core/types/index.js:619

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

Transformer parcel/packages/core/types/index.js:683

The methods for a transformer plugin. 

type Transformer = {|
  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>>,
|}