API

The remaining types specified in `@parcel/plugin`

The most important data types are listed on the page of the relevant plugin type.

FilePath packages-v3/plugin/src/types.ts:13

Type
type FilePath = string;
Referenced by:
Asset, Bundle, Namer, PluginOptions, ResolveFn, ResolveResult, Target

Glob packages-v3/plugin/src/types.ts:14

Type
type Glob = string;

PackageName packages-v3/plugin/src/types.ts:15

Type
type PackageName = string;
Referenced by:
Target

SemverRange packages-v3/plugin/src/types.ts:16

Type
type SemverRange = string;
Referenced by:
Dependency, DependencyOptions

DependencySpecifier packages-v3/plugin/src/types.ts:18

See Dependency

Type
type DependencySpecifier = string;
Referenced by:
Dependency, DependencyOptions, Resolver

Async packages-v3/plugin/src/types.ts:21

Plugins may return either a value or a promise for it.

Type
type Async<T> = T | Promise<T>;
Referenced by:
Namer, Optimizer, Reporter, Resolver, Transformer

JSONObject packages-v3/plugin/src/types.ts:24

A JSON object (as in "map")

type JSONObject = {
  [key: string]: JSONValue;
}
Referenced by:
JSONValue

JSONValue packages-v3/plugin/src/types.ts:25

Type
type JSONValue =
  | null
  | boolean
  | number
  | string
  | Array<JSONValue>
  | JSONObject;
Referenced by:
JSONObject

SourceMapJSON packages-v3/plugin/src/types.ts:34

A source map in the standard JSON format (version 3).

type SourceMapJSON = {
  version: number;
  sources: Array<string>;
  mappings: string;
  names?: Array<string>;
  sourcesContent?: Array<string | null>;
  sourceRoot?: string;
  file?: string;
  [key: string]: unknown;
}
Referenced by:
Asset, MutableAsset

Location packages-v3/plugin/src/types.ts:46

Line/column positions are 1-based (so 1 is the first line/column).

type Location = {
  readonly line: number;
  readonly column: number;
}
Referenced by:
DependencyOptions, DiagnosticCodeHighlight, SourceLocation

SourceLocation packages-v3/plugin/src/types.ts:51 

type SourceLocation = {
  readonly filePath: string;
  readonly start: Location;

inclusive

  readonly end: Location;

exclusive

}
Referenced by:
Dependency

DiagnosticSeverity packages-v3/plugin/src/types.ts:67

  • error: Fails the build.
    • warning: Logged, but does not fail the build.
    • sourceError: An error in source code in the project, or a warning in node_modules.
    • info: An informative message.
Type
type DiagnosticSeverity = 'error' | 'warning' | 'sourceError' | 'info';
Referenced by:
DiagnosticOptions

DiagnosticCodeHighlight packages-v3/plugin/src/types.ts:69 

type DiagnosticCodeHighlight = {
  start: Location;

Location of the first character that should get highlighted for this highlight.

  end?: Location;

Location of the last character that should get highlighted for this highlight. Defaults to start.

  message?: string | null;

A message that should be displayed at this location in the code.

}
Referenced by:
DiagnosticCodeFrame

DiagnosticCodeFrame packages-v3/plugin/src/types.ts:83

Describes how to format a code frame. A code frame is a visualization of a piece of code with a certain amount of code highlights that point to certain chunk(s) inside the code.

type DiagnosticCodeFrame = {
  code?: string | null;

The contents of the source file, if different from the file. If omitted, the file is read.

  filePath?: string | null;

Absolute path of the file this code frame is about. Diagnostics passed to reporters use url instead.

  url?: string | null;

URL of the file this code frame is about. Files on disk use file: URLs.

  language?: string | null;

Language (file extension) of the code, used for syntax highlighting.

  codeHighlights: Array<DiagnosticCodeHighlight>;
}
Referenced by:
DiagnosticOptions

DiagnosticOptions packages-v3/plugin/src/types.ts:104

A style agnostic way of emitting errors, warnings and info. Reporters are responsible for rendering the message, codeframes, hints, ...

Diagnostics passed to reporters have every field.

type DiagnosticOptions = {
  message: string;

This is the message you want to log.

  origin?: string | null;

Name of plugin or file that threw this error. Defaults to the plugin's name in .parcelrc.

  codeFrames?: Array<DiagnosticCodeFrame>;

Code frames point to certain location(s) in the file(s) this diagnostic is linked to.

  hints?: Array<string>;

A list of strings that suggest ways to resolve this issue

  severity?: DiagnosticSeverity;

Default value: 'error'

  documentationURL?: string | null;

A URL to documentation to learn more about the diagnostic.

}
Referenced by:
BuildFailureEvent, Diagnostic, LogEvent

LogLevel packages-v3/plugin/src/types.ts:119

Type
type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'verbose';
Referenced by:
LogEvent, PluginOptions

BuildMode packages-v3/plugin/src/types.ts:120

Type
type BuildMode = 'development' | 'production' | string;
Referenced by:
PluginOptions

HMROptions packages-v3/plugin/src/types.ts:122 

type HMROptions = {
  readonly host: string;
  readonly port: number;
}
Referenced by:
PluginOptions

PluginOptions packages-v3/plugin/src/types.ts:127 

interface PluginOptions {
  readonly mode: BuildMode;
  readonly env: Readonly<Record<string, string>>;
  readonly logLevel: LogLevel;
  readonly hmrOptions: HMROptions | undefined;
  readonly projectRoot: FilePath;
}
Referenced by:
Namer, Optimizer, ReporterContext, Resolver, Transformer

Engines packages-v3/plugin/src/types.ts:139

Corresponds to pkg#engines, resolved to minimum versions, which are formatted like >= 18.2.

type Engines = {
  readonly browsers: string;

The minimum browser versions, e.g. chrome >= 63, firefox >= 67, safari >= 11.1. Empty if none.

  readonly electron: string | null;
  readonly node: string | null;
  readonly parcel: string | null;
}
Referenced by:
Target

TargetSourceMapOptions packages-v3/plugin/src/types.ts:148

Corresponds to pkg#targets.*.sourceMap

type TargetSourceMapOptions = {
  readonly sourceRoot: string | null;
  readonly inline: boolean | null;
  readonly inlineSources: boolean | null;
}
Referenced by:
Target

EnvironmentContext packages-v3/plugin/src/types.ts:155

In which environment the output should run (influces e.g. bundle loaders)

Type
type EnvironmentContext =
  | 'browser'
  | 'web-worker'
  | 'service-worker'
  | 'worklet'
  | 'node'
  | 'electron-main'
  | 'electron-renderer'
  | 'react-client'
  | 'react-server';
Referenced by:
Target

OutputFormat packages-v3/plugin/src/types.ts:167

The JS module format for the bundle output

Type
type OutputFormat = 'esmodule' | 'commonjs' | 'global';
Referenced by:
Target

SourceType packages-v3/plugin/src/types.ts:169

Type
type SourceType = 'script' | 'module';
Referenced by:
Target

Target packages-v3/plugin/src/types.ts:174

Where and how an asset or bundle will run.

interface Target {
  readonly distDir: FilePath;

The output folder

  readonly publicUrl: string;
  readonly engines: Engines;
  readonly includeNodeModules:
    | boolean
    | Array<PackageName>
    | Record<PackageName, boolean>;

Whether to include all/none packages (true / false), an array of package names to include, or an object (of a package is not specified, it's included).

  readonly sourceMap: TargetSourceMapOptions | null;
  readonly environment: EnvironmentContext;
  readonly outputFormat: OutputFormat;
  readonly sourceType: SourceType;
  readonly isLibrary: boolean;

Whether this is a library build (e.g. less loaders)

  readonly shouldOptimize: boolean;

Whether the output should be minified.

  isBrowser(): boolean;

Whether environment specifies a browser context.

  isNode(): boolean;

Whether environment specifies a node context.

  isElectron(): boolean;

Whether environment specifies an electron context.

  isServer(): boolean;

Whether environment specifies a server context (node or react-server).

  isWorker(): boolean;

Whether environment specifies a worker context.

  isWorklet(): boolean;

Whether environment specifies a worklet context.

}
Referenced by:
Asset, Bundle, Dependency, DependencyOptions

DependencyPriority packages-v3/plugin/src/types.ts:218

Type
type DependencyPriority = 'sync' | 'parallel' | 'lazy';
Referenced by:
Dependency, DependencyOptions

SpecifierType packages-v3/plugin/src/types.ts:219

Type
type SpecifierType = 'commonjs' | 'esm' | 'url' | 'custom';
Referenced by:
Dependency, DependencyOptions, ResolveOptions

BundleBehavior packages-v3/plugin/src/types.ts:220

Type
type BundleBehavior = 'inline' | 'isolated';
Referenced by:
Asset, Bundle, Dependency, DependencyOptions, MutableAsset

ImportType packages-v3/plugin/src/types.ts:230

How the resolved asset is used by the importing asset.

  • javascript: Imported as a JavaScript module.
  • stylesheet: Imported as a CSS stylesheet.
  • url: Referenced by URL.
  • text: Imported as a string.
  • bytes: Imported as binary data.
Type
type ImportType = 'javascript' | 'stylesheet' | 'url' | 'text' | 'bytes';
Referenced by:
Dependency, DependencyOptions

PackageCondition packages-v3/plugin/src/types.ts:233

The package.json "exports" and "imports" conditions supported by Parcel.

Type
type PackageCondition =
  | 'import'
  | 'require'
  | 'module'
  | 'node'
  | 'browser'
  | 'worker'
  | 'worklet'
  | 'electron'
  | 'development'
  | 'production'
  | 'types'
  | 'default'
  | 'style'
  | 'sass'
  | 'less'
  | 'stylus'
  | 'react-server'
  | 'source';
Referenced by:
Dependency, DependencyOptions

Bundle packages-v3/plugin/src/types.ts:585

A Bundle (a collection of assets)

Bundles can only be accessed during the plugin call they were passed to.

interface Bundle {
  readonly type: string;

The type of the bundle.

  readonly target: Target;

The bundle's target.

  readonly isEntry: boolean;

Whether the bundle is an entry.

  readonly needsStableName: boolean;

Indicates that the bundle's file name should be stable over time, even when the content of the bundle changes. This is useful for entries that a user would manually enter the URL for, as well as for things like service workers or RSS feeds, where the URL must remain consistent over time.

  readonly bundleBehavior: BundleBehavior | undefined;

Controls the behavior of the bundle.

  • inline: Inline bundles are not written to a separate file, but embedded into the parent bundle.
  • isolated: The bundle will be isolated from its parents. Shared assets will be duplicated.
  readonly hashReference: string;

A placeholder for the bundle's content hash. A namer must include it exactly once in the name of a bundle that may be content hashed. It is replaced with a content hash of the bundle after packaging and optimizing.

  readonly filePath: FilePath | null;

The absolute path the bundle is written to, once it is known. null for inline bundles, before the bundle is named, and while a content hashed name is unknown.

  readonly name: string | null;

The bundle's name: its file path relative to its target's distDir. null until it can be read, i.e. before the bundle is named, or while a content hashed name is unknown.

  getEntryAssets(): Array<Asset>;

Returns the assets that are executed immediately when the bundle is loaded. Some bundles may not have any entry assets, for example, shared bundles.

  getMainEntry(): Asset | undefined;

Returns the main entry of the bundle, which will provide the bundle's exports. Some bundles do not have a main entry, for example, shared bundles.

  hasAsset(asset: Asset): boolean;

Returns whether the bundle includes the given asset.

}
Referenced by:
BundleGraph, Namer, Optimizer

BundleGraph packages-v3/plugin/src/types.ts:649

A Graph that contains Bundle-s.

interface BundleGraph {
  getBundles(): Array<Bundle>;

Returns a list of bundles in the bundle graph.

  getEntryBundles(): Array<Bundle>;

Returns a list of entry bundles.

  getReferencedBundles(
    bundle: Bundle,
    options?: {
      recursive?: boolean;
    },
  ): Array<Bundle>;

Returns a list of bundles that are referenced by this bundle.

  getBundlesInBundleGroup(bundle: Bundle): Array<Bundle>;

Returns the bundles that code in the bundle's execution context may load: everything reachable through bundle references and Parcel's loader, without entering other execution contexts (e.g. workers). The bundle itself is not included.

  getBundleDependencies(bundle: Bundle): Array<Bundle>;

Returns the bundles that dependencies of the bundle's assets resolve to, e.g. lazy, isolated, inline and URL references.

  getResolvedAsset(dependency: Dependency): Asset | undefined;

Returns the asset that the dependency resolved to, if any.

  getReferencedBundle(dependency: Dependency): Bundle | undefined;

Returns the bundle that the dependency references, if it resolved to another bundle.

}
Referenced by:
BuildSuccessEvent, Namer, Optimizer

Diagnostic packages-v3/plugin/src/PluginAPI.ts:53

An error carrying one or more diagnostics. Throw it from a plugin to fail with them, or pass it to a console method to log them at that level.

class Diagnostic extends Error {
  readonly diagnostics: Array<DiagnosticOptions>;
  constructor(diagnostic: DiagnosticOptions | Array<DiagnosticOptions>);
}