0
# @parcel/types
1

2
@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.
3

4
## Package Information
5

6
- **Package Name**: @parcel/types
7
- **Package Type**: npm
8
- **Language**: TypeScript (Flow source)
9
- **Installation**: `npm install @parcel/types`
10

11
## Core Imports
12

13
```typescript
14
import type {
15
  InitialParcelOptions,
16
  Asset,
17
  Bundle,
18
  Transformer,
19
  Environment,
20
  Target,
21
  FilePath,
22
  DependencySpecifier,
23
  LogLevel,
24
  BackendType,
25
  DetailedReportOptions,
26
  FeatureFlags
27
} from '@parcel/types';
28
```
29

30
For specific imports:
31

32
```typescript
33
import type { InitialParcelOptions } from '@parcel/types';
34
import type { Asset, MutableAsset } from '@parcel/types';
35
import type { Bundle, BundleGraph } from '@parcel/types';
36
import type { FilePath, DependencySpecifier } from '@parcel/types';
37
import type { LogLevel, BackendType } from '@parcel/types';
38
```
39

40
## Basic Usage
41

42
```typescript
43
import type { 
44
  InitialParcelOptions, 
45
  Transformer, 
46
  Asset, 
47
  TransformerResult 
48
} from '@parcel/types';
49

50
// Define Parcel build options
51
const options: InitialParcelOptions = {
52
  entries: ['src/index.html'],
53
  defaultConfig: '@parcel/config-default',
54
  mode: 'production',
55
  targets: {
56
    main: {
57
      distDir: 'dist'
58
    }
59
  }
60
};
61

62
// Implement a custom transformer plugin
63
class MyTransformer implements Transformer {
64
  async transform({ asset }: { asset: MutableAsset }): Promise<TransformerResult[]> {
65
    const code = await asset.getCode();
66
    const transformedCode = processCode(code);
67
    
68
    asset.setCode(transformedCode);
69
    
70
    return [asset];
71
  }
72
}
73
```
74

75
## Architecture
76

77
@parcel/types is built around several core systems:
78

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

87
## Capabilities
88

89
### Build Configuration
90

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

93
```typescript { .api }
94
interface InitialParcelOptions {
95
  entries?: FilePath | Array<FilePath>;
96
  config?: DependencySpecifier;
97
  defaultConfig?: DependencySpecifier;
98
  targets?: Array<string> | {[string]: TargetDescriptor};
99
  mode?: BuildMode;
100
  env?: EnvMap;
101
  shouldDisableCache?: boolean;
102
  cacheDir?: FilePath;
103
  watchDir?: FilePath;
104
  watchBackend?: BackendType;
105
  shouldContentHash?: boolean;
106
  serveOptions?: InitialServerOptions | false;
107
  shouldAutoInstall?: boolean;
108
  logLevel?: LogLevel;
109
  shouldProfile?: boolean;
110
  shouldTrace?: boolean;
111
  shouldBuildLazily?: boolean;
112
  inputFS?: FileSystem;
113
  outputFS?: FileSystem;
114
  cache?: Cache;
115
  workerFarm?: WorkerFarm;
116
  packageManager?: PackageManager;
117
  detailedReport?: DetailedReportOptions;
118
  featureFlags?: Partial<FeatureFlags>;
119
}
120

121
type BuildMode = 'development' | 'production' | string;
122
```
123

124
[Build Configuration](./build-configuration.md)
125

126
### Asset System
127

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

130
```typescript { .api }
131
interface Asset {
132
  readonly id: string;
133
  readonly filePath: FilePath;
134
  readonly type: string;
135
  readonly env: Environment;
136
  readonly isSource: boolean;
137
  
138
  getCode(): Promise<string>;
139
  getBuffer(): Promise<Buffer>;
140
  getAST(): Promise<AST>;
141
  getDependencies(): Array<Dependency>;
142
}
143

144
interface MutableAsset extends BaseAsset {
145
  setCode(code: string): void;
146
  setAST(ast: AST): void;
147
  setMap(map: ?SourceMap): void;
148
  addDependency(dep: DependencyOptions): string;
149
  addURLDependency(url: string, opts?: DependencyOptions): string;
150
}
151
```
152

153
[Asset System](./asset-system.md)
154

155
### Plugin System
156

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

159
```typescript { .api }
160
interface Transformer<ConfigType = any> {
161
  loadConfig?(opts: PluginOptions): Promise<ConfigType>;
162
  transform(opts: {
163
    asset: MutableAsset;
164
    config: ConfigType;
165
    options: PluginOptions;
166
  }): Promise<Array<TransformerResult>>;
167
}
168

169
interface Resolver<ConfigType = any> {
170
  resolve(opts: {
171
    dependency: Dependency;
172
    options: PluginOptions;
173
    config: ConfigType;
174
  }): Promise<?ResolveResult>;
175
}
176

177
interface Bundler<ConfigType = any> {
178
  bundle(opts: {
179
    bundleGraph: MutableBundleGraph;
180
    config: ConfigType;
181
    options: PluginOptions;
182
  }): Promise<void>;
183
}
184
```
185

186
[Plugin System](./plugin-system.md)
187

188
### Bundle System
189

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

192
```typescript { .api }
193
interface Bundle {
194
  readonly id: string;
195
  readonly type: string;
196
  readonly env: Environment;
197
  readonly target: Target;
198
  readonly needsStableName: ?boolean;
199
  readonly bundleBehavior: ?BundleBehavior;
200
  readonly isSplittable: ?boolean;
201
  readonly hashReference: string;
202
  
203
  getEntryAssets(): Array<Asset>;
204
  getMainEntry(): ?Asset;
205
  hasAsset(asset: Asset): boolean;
206
  hasDependency(dependency: Dependency): boolean;
207
  traverseAssets<TContext>(visit: GraphVisitor<Asset, TContext>, startAsset?: Asset): ?TContext;
208
  traverse<TContext>(visit: GraphVisitor<BundleTraversable, TContext>): ?TContext;
209
  getContentHash(): string;
210
}
211

212
interface BundleGraph<TBundle: Bundle = Bundle> {
213
  getAssetById(id: string): Asset;
214
  getAssetPublicId(asset: Asset): string;
215
  getBundles(opts?: {includeInline: boolean}): Array<TBundle>;
216
  getChildBundles(bundle: Bundle): Array<TBundle>;
217
  getParentBundles(bundle: Bundle): Array<TBundle>;
218
  resolveAsyncDependency(
219
    dependency: Dependency, 
220
    bundle: ?Bundle
221
  ): ?({type: 'bundle_group', value: BundleGroup} | {type: 'asset', value: Asset});
222
}
223
```
224

225
[Bundle System](./bundle-system.md)
226

227
### Environment System
228

229
Target environment configuration, engine requirements, and feature detection.
230

231
```typescript { .api }
232
interface Environment {
233
  readonly context: EnvironmentContext;
234
  readonly engines: Engines;
235
  readonly outputFormat: OutputFormat;
236
  readonly sourceType: SourceType;
237
  readonly isLibrary: boolean;
238
  readonly shouldOptimize: boolean;
239
  readonly shouldScopeHoist: boolean;
240
  
241
  isBrowser(): boolean;
242
  isNode(): boolean;
243
  isServer(): boolean;
244
  isElectron(): boolean;
245
  isWorker(): boolean;
246
  supports(feature: EnvironmentFeature): boolean;
247
}
248

249
type EnvironmentContext = 
250
  | 'browser' 
251
  | 'web-worker' 
252
  | 'service-worker'
253
  | 'node' 
254
  | 'electron-main' 
255
  | 'electron-renderer';
256

257
type OutputFormat = 'esmodule' | 'commonjs' | 'global';
258
```
259

260
[Environment System](./environment-system.md)
261

262
### File System
263

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

266
```typescript { .api }
267
interface FileSystem {
268
  readFile(filePath: FilePath): Promise<Buffer>;
269
  readFile(filePath: FilePath, encoding: Encoding): Promise<string>;
270
  writeFile(filePath: FilePath, contents: Buffer | string): Promise<void>;
271
  stat(filePath: FilePath): Promise<Stats>;
272
  readdir(path: FilePath): Promise<Array<string>>;
273
  exists(path: FilePath): Promise<boolean>;
274
  mkdirp(path: FilePath): Promise<void>;
275
  watch(dir: FilePath, fn: (err: ?Error, events: Array<Event>) => void): AsyncSubscription;
276
}
277

278
interface Cache {
279
  get<T>(key: string): Promise<?T>;
280
  set(key: string, value: mixed): Promise<void>;
281
  getBlob(key: string): Promise<Buffer>;
282
  setBlob(key: string, contents: Buffer | string): Promise<void>;
283
}
284
```
285

286
[File System](./file-system.md)
287

288
## Types
289

290
### Core Types
291

292
```typescript { .api }
293
type FilePath = string;
294
type PackageName = string;
295
type DependencySpecifier = string;
296
type Glob = string;
297
type Symbol = string;
298
type Semver = string;
299
type SemverRange = string;
300
type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'verbose';
301
type BackendType = 'fs-events' | 'watchman' | 'brute-force';
302
type GlobPattern = string;
303

304
type JSONValue = 
305
  | null 
306
  | boolean 
307
  | number 
308
  | string 
309
  | Array<JSONValue> 
310
  | JSONObject;
311

312
interface JSONObject {
313
  [key: string]: JSONValue;
314
}
315

316
interface DetailedReportOptions {
317
  assetsPerBundle?: number;
318
}
319

320
interface Event {
321
  type: 'create' | 'update' | 'delete';
322
  path: string;
323
}
324

325
interface BundleGroup {
326
  target: Target;
327
  entryAssetId: string;
328
}
329

330
type BundleTraversable = 
331
  | {type: 'asset', value: Asset}
332
  | {type: 'dependency', value: Dependency};
333

334
type BundleBehavior = 'inline' | 'isolated';
335

336
type EnvMap = typeof process.env;
337
type Async<T> = T | Promise<T>;
338
type Blob = string | Buffer | Readable;
339
```