or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

asset-system.mdbuild-configuration.mdbundle-system.mdenvironment-system.mdfile-system.mdindex.mdplugin-system.md
tile.json

tessl/npm-parcel--types

TypeScript type definitions for the Parcel bundler providing comprehensive interfaces for build configuration, plugins, assets, and bundle management

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@parcel/types@2.15.x

To install, run

npx @tessl/cli install tessl/npm-parcel--types@2.15.0

index.mddocs/

@parcel/types

@parcel/types provides comprehensive TypeScript type definitions for the Parcel bundler ecosystem. It serves as the public API entry point, re-exporting all types from @parcel/types-internal while adding WorkerFarm integration types. The package enables type-safe development when building applications with Parcel or developing Parcel plugins.

Package Information

  • Package Name: @parcel/types
  • Package Type: npm
  • Language: TypeScript (Flow source)
  • Installation: npm install @parcel/types

Core Imports

import type {
  InitialParcelOptions,
  Asset,
  Bundle,
  Transformer,
  Environment,
  Target,
  FilePath,
  DependencySpecifier,
  LogLevel,
  BackendType,
  DetailedReportOptions,
  FeatureFlags
} from '@parcel/types';

For specific imports:

import type { InitialParcelOptions } from '@parcel/types';
import type { Asset, MutableAsset } from '@parcel/types';
import type { Bundle, BundleGraph } from '@parcel/types';
import type { FilePath, DependencySpecifier } from '@parcel/types';
import type { LogLevel, BackendType } from '@parcel/types';

Basic Usage

import type { 
  InitialParcelOptions, 
  Transformer, 
  Asset, 
  TransformerResult 
} from '@parcel/types';

// Define Parcel build options
const options: InitialParcelOptions = {
  entries: ['src/index.html'],
  defaultConfig: '@parcel/config-default',
  mode: 'production',
  targets: {
    main: {
      distDir: 'dist'
    }
  }
};

// Implement a custom transformer plugin
class MyTransformer implements Transformer {
  async transform({ asset }: { asset: MutableAsset }): Promise<TransformerResult[]> {
    const code = await asset.getCode();
    const transformedCode = processCode(code);
    
    asset.setCode(transformedCode);
    
    return [asset];
  }
}

Architecture

@parcel/types is built around several core systems:

  • Build Configuration: InitialParcelOptions and related types for configuring Parcel builds
  • Asset System: Immutable and mutable asset representations with dependency tracking
  • Plugin Architecture: Comprehensive interfaces for all plugin types (transformers, resolvers, bundlers, etc.)
  • Bundle System: Bundle creation, optimization, and graph management
  • Environment System: Target environment configuration and feature detection
  • File System Abstraction: Cross-platform file operations with caching and invalidation
  • Type Safety: Complete TypeScript coverage for all public APIs

Capabilities

Build Configuration

Core types for configuring Parcel builds, including entry points, targets, caching, and development server options.

interface InitialParcelOptions {
  entries?: FilePath | Array<FilePath>;
  config?: DependencySpecifier;
  defaultConfig?: DependencySpecifier;
  targets?: Array<string> | {[string]: TargetDescriptor};
  mode?: BuildMode;
  env?: EnvMap;
  shouldDisableCache?: boolean;
  cacheDir?: FilePath;
  watchDir?: FilePath;
  watchBackend?: BackendType;
  shouldContentHash?: boolean;
  serveOptions?: InitialServerOptions | false;
  shouldAutoInstall?: boolean;
  logLevel?: LogLevel;
  shouldProfile?: boolean;
  shouldTrace?: boolean;
  shouldBuildLazily?: boolean;
  inputFS?: FileSystem;
  outputFS?: FileSystem;
  cache?: Cache;
  workerFarm?: WorkerFarm;
  packageManager?: PackageManager;
  detailedReport?: DetailedReportOptions;
  featureFlags?: Partial<FeatureFlags>;
}

type BuildMode = 'development' | 'production' | string;

Build Configuration

Asset System

Asset representation and manipulation for the build pipeline, including dependency tracking and transformation.

interface Asset {
  readonly id: string;
  readonly filePath: FilePath;
  readonly type: string;
  readonly env: Environment;
  readonly isSource: boolean;
  
  getCode(): Promise<string>;
  getBuffer(): Promise<Buffer>;
  getAST(): Promise<AST>;
  getDependencies(): Array<Dependency>;
}

interface MutableAsset extends BaseAsset {
  setCode(code: string): void;
  setAST(ast: AST): void;
  setMap(map: ?SourceMap): void;
  addDependency(dep: DependencyOptions): string;
  addURLDependency(url: string, opts?: DependencyOptions): string;
}

Asset System

Plugin System

Comprehensive plugin interfaces for extending Parcel's build pipeline at every stage.

interface Transformer<ConfigType = any> {
  loadConfig?(opts: PluginOptions): Promise<ConfigType>;
  transform(opts: {
    asset: MutableAsset;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<Array<TransformerResult>>;
}

interface Resolver<ConfigType = any> {
  resolve(opts: {
    dependency: Dependency;
    options: PluginOptions;
    config: ConfigType;
  }): Promise<?ResolveResult>;
}

interface Bundler<ConfigType = any> {
  bundle(opts: {
    bundleGraph: MutableBundleGraph;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<void>;
}

Plugin System

Bundle System

Bundle creation, optimization, and graph traversal for the final build output.

interface Bundle {
  readonly id: string;
  readonly type: string;
  readonly env: Environment;
  readonly target: Target;
  readonly needsStableName: ?boolean;
  readonly bundleBehavior: ?BundleBehavior;
  readonly isSplittable: ?boolean;
  readonly hashReference: string;
  
  getEntryAssets(): Array<Asset>;
  getMainEntry(): ?Asset;
  hasAsset(asset: Asset): boolean;
  hasDependency(dependency: Dependency): boolean;
  traverseAssets<TContext>(visit: GraphVisitor<Asset, TContext>, startAsset?: Asset): ?TContext;
  traverse<TContext>(visit: GraphVisitor<BundleTraversable, TContext>): ?TContext;
  getContentHash(): string;
}

interface BundleGraph<TBundle: Bundle = Bundle> {
  getAssetById(id: string): Asset;
  getAssetPublicId(asset: Asset): string;
  getBundles(opts?: {includeInline: boolean}): Array<TBundle>;
  getChildBundles(bundle: Bundle): Array<TBundle>;
  getParentBundles(bundle: Bundle): Array<TBundle>;
  resolveAsyncDependency(
    dependency: Dependency, 
    bundle: ?Bundle
  ): ?({type: 'bundle_group', value: BundleGroup} | {type: 'asset', value: Asset});
}

Bundle System

Environment System

Target environment configuration, engine requirements, and feature detection.

interface Environment {
  readonly context: EnvironmentContext;
  readonly engines: Engines;
  readonly outputFormat: OutputFormat;
  readonly sourceType: SourceType;
  readonly isLibrary: boolean;
  readonly shouldOptimize: boolean;
  readonly shouldScopeHoist: boolean;
  
  isBrowser(): boolean;
  isNode(): boolean;
  isServer(): boolean;
  isElectron(): boolean;
  isWorker(): boolean;
  supports(feature: EnvironmentFeature): boolean;
}

type EnvironmentContext = 
  | 'browser' 
  | 'web-worker' 
  | 'service-worker'
  | 'node' 
  | 'electron-main' 
  | 'electron-renderer';

type OutputFormat = 'esmodule' | 'commonjs' | 'global';

Environment System

File System

Cross-platform file system abstraction with caching, watching, and invalidation support.

interface FileSystem {
  readFile(filePath: FilePath): Promise<Buffer>;
  readFile(filePath: FilePath, encoding: Encoding): Promise<string>;
  writeFile(filePath: FilePath, contents: Buffer | string): Promise<void>;
  stat(filePath: FilePath): Promise<Stats>;
  readdir(path: FilePath): Promise<Array<string>>;
  exists(path: FilePath): Promise<boolean>;
  mkdirp(path: FilePath): Promise<void>;
  watch(dir: FilePath, fn: (err: ?Error, events: Array<Event>) => void): AsyncSubscription;
}

interface Cache {
  get<T>(key: string): Promise<?T>;
  set(key: string, value: mixed): Promise<void>;
  getBlob(key: string): Promise<Buffer>;
  setBlob(key: string, contents: Buffer | string): Promise<void>;
}

File System

Types

Core Types

type FilePath = string;
type PackageName = string;
type DependencySpecifier = string;
type Glob = string;
type Symbol = string;
type Semver = string;
type SemverRange = string;
type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'verbose';
type BackendType = 'fs-events' | 'watchman' | 'brute-force';
type GlobPattern = string;

type JSONValue = 
  | null 
  | boolean 
  | number 
  | string 
  | Array<JSONValue> 
  | JSONObject;

interface JSONObject {
  [key: string]: JSONValue;
}

interface DetailedReportOptions {
  assetsPerBundle?: number;
}

interface Event {
  type: 'create' | 'update' | 'delete';
  path: string;
}

interface BundleGroup {
  target: Target;
  entryAssetId: string;
}

type BundleTraversable = 
  | {type: 'asset', value: Asset}
  | {type: 'dependency', value: Dependency};

type BundleBehavior = 'inline' | 'isolated';

type EnvMap = typeof process.env;
type Async<T> = T | Promise<T>;
type Blob = string | Buffer | Readable;