@parcel/plugin

@parcel/plugin provides the core plugin API for the Parcel bundler ecosystem, serving as a foundational library that enables developers to create custom plugins for extending Parcel's functionality. It exports base classes for all major plugin types including transformers, resolvers, bundlers, namers, runtimes, packagers, optimizers, compressors, reporters, and validators.

Package Information

• Package Name: @parcel/plugin
• Package Type: npm
• Language: JavaScript (with Flow and TypeScript definitions)
• Installation: npm install @parcel/plugin

Core Imports

import { Transformer, Resolver, Bundler } from "@parcel/plugin";

For CommonJS:

const { Transformer, Resolver, Bundler } = require("@parcel/plugin");

Basic Usage

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

// Create a custom transformer plugin
export default new Transformer({
  transform({asset, config, resolve, options, logger, tracer}) {
    // Transform the asset
    const transformedCode = processAsset(asset.getCode());
    asset.setCode(transformedCode);
    return [asset];
  }
});

Architecture

The @parcel/plugin package is built around the Parcel plugin system architecture:

• Plugin Base Classes: Ten base classes corresponding to different build phases
• Type Safety: Full Flow and TypeScript integration with generic configuration types
• Configuration System: Symbol-based configuration storage for plugin options
• Pipeline Integration: Plugins integrate into Parcel's build pipeline phases
• Extensibility: Each plugin type provides hooks for customizing specific build behaviors

Capabilities

Asset Transformation

Transform and process individual assets during the build process. Handles parsing, transforming, and generating code for different file types.

export declare class Transformer<T> {
  constructor(opts: TransformerOpts<T>);
}

Asset Transformation

Module Resolution

Resolve import and require statements to actual file paths and modules. Enables custom resolution logic for different module systems.

export declare class Resolver<T> {
  constructor(opts: ResolverOpts<T>);
}

Module Resolution

Bundle Generation

Control how assets are grouped into bundles and optimize the bundle graph for performance and caching.

export declare class Bundler<T> {
  constructor(opts: BundlerOpts<T>);
}

Bundle Generation

Bundle Naming

Generate output filenames for bundles based on content, configuration, and optimization strategies.

export declare class Namer<T> {
  constructor(opts: NamerOpts<T>);
}

Bundle Naming

Runtime Injection

Inject runtime code into bundles for features like hot module replacement, dynamic imports, and environment-specific code.

export declare class Runtime<T> {
  constructor(opts: RuntimeOpts<T>);
}

Runtime Injection

Asset Packaging

Package bundles into final output formats, handling different target environments and module systems.

export declare class Packager<C, B> {
  constructor(opts: PackagerOpts<C, B>);
}

Asset Packaging

Code Optimization

Optimize bundled code through minification, tree shaking, and other performance improvements.

export declare class Optimizer<C, B> {
  constructor(opts: OptimizerOpts<C, B>);
}

Code Optimization

Bundle Compression

Compress bundle outputs using various compression algorithms for reduced file sizes.

export declare class Compressor {
  constructor(opts: CompressorOpts);
}

Bundle Compression

Build Reporting

Report build progress, errors, and other events to users and external tools.

export declare class Reporter {
  constructor(opts: ReporterOpts);
}

Build Reporting

Code Validation

Validate code for errors, style issues, and other quality concerns during the build process.

export declare class Validator<T> {
  constructor(opts: ValidatorOpts);
}

Code Validation

Core Types

All plugin base classes accept configuration objects and store them using a symbol-based approach:

// Internal configuration storage symbol
const CONFIG: symbol;

// All plugin options types are imported from @parcel/types
type TransformerOpts<T> = import("@parcel/types").Transformer<T>;
type ResolverOpts<T> = import("@parcel/types").Resolver<T>;
type BundlerOpts<T> = import("@parcel/types").Bundler<T>;
type NamerOpts<T> = import("@parcel/types").Namer<T>;
type RuntimeOpts<T> = import("@parcel/types").Runtime<T>;
type ValidatorOpts = import("@parcel/types").Validator;
type PackagerOpts<C, B> = import("@parcel/types").Packager<C, B>;
type OptimizerOpts<C, B> = import("@parcel/types").Optimizer<C, B>;
type CompressorOpts = import("@parcel/types").Compressor;
type ReporterOpts = import("@parcel/types").Reporter;