0
# @parcel/plugin
1

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

4
## Package Information
5

6
- **Package Name**: @parcel/plugin
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow and TypeScript definitions)
9
- **Installation**: `npm install @parcel/plugin`
10

11
## Core Imports
12

13
```javascript
14
import { Transformer, Resolver, Bundler } from "@parcel/plugin";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Transformer, Resolver, Bundler } = require("@parcel/plugin");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import { Transformer } from "@parcel/plugin";
27

28
// Create a custom transformer plugin
29
export default new Transformer({
30
  transform({asset, config, resolve, options, logger, tracer}) {
31
    // Transform the asset
32
    const transformedCode = processAsset(asset.getCode());
33
    asset.setCode(transformedCode);
34
    return [asset];
35
  }
36
});
37
```
38

39
## Architecture
40

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

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

49
## Capabilities
50

51
### Asset Transformation
52

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

55
```typescript { .api }
56
export declare class Transformer<T> {
57
  constructor(opts: TransformerOpts<T>);
58
}
59
```
60

61
[Asset Transformation](./transformation.md)
62

63
### Module Resolution
64

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

67
```typescript { .api }
68
export declare class Resolver<T> {
69
  constructor(opts: ResolverOpts<T>);
70
}
71
```
72

73
[Module Resolution](./resolution.md)
74

75
### Bundle Generation
76

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

79
```typescript { .api }
80
export declare class Bundler<T> {
81
  constructor(opts: BundlerOpts<T>);
82
}
83
```
84

85
[Bundle Generation](./bundling.md)
86

87
### Bundle Naming
88

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

91
```typescript { .api }
92
export declare class Namer<T> {
93
  constructor(opts: NamerOpts<T>);
94
}
95
```
96

97
[Bundle Naming](./naming.md)
98

99
### Runtime Injection
100

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

103
```typescript { .api }
104
export declare class Runtime<T> {
105
  constructor(opts: RuntimeOpts<T>);
106
}
107
```
108

109
[Runtime Injection](./runtime.md)
110

111
### Asset Packaging
112

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

115
```typescript { .api }
116
export declare class Packager<C, B> {
117
  constructor(opts: PackagerOpts<C, B>);
118
}
119
```
120

121
[Asset Packaging](./packaging.md)
122

123
### Code Optimization
124

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

127
```typescript { .api }
128
export declare class Optimizer<C, B> {
129
  constructor(opts: OptimizerOpts<C, B>);
130
}
131
```
132

133
[Code Optimization](./optimization.md)
134

135
### Bundle Compression
136

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

139
```typescript { .api }
140
export declare class Compressor {
141
  constructor(opts: CompressorOpts);
142
}
143
```
144

145
[Bundle Compression](./compression.md)
146

147
### Build Reporting
148

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

151
```typescript { .api }
152
export declare class Reporter {
153
  constructor(opts: ReporterOpts);
154
}
155
```
156

157
[Build Reporting](./reporting.md)
158

159
### Code Validation
160

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

163
```typescript { .api }
164
export declare class Validator<T> {
165
  constructor(opts: ValidatorOpts);
166
}
167
```
168

169
[Code Validation](./validation.md)
170

171
## Core Types
172

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

175
```typescript { .api }
176
// Internal configuration storage symbol
177
const CONFIG: symbol;
178

179
// All plugin options types are imported from @parcel/types
180
type TransformerOpts<T> = import("@parcel/types").Transformer<T>;
181
type ResolverOpts<T> = import("@parcel/types").Resolver<T>;
182
type BundlerOpts<T> = import("@parcel/types").Bundler<T>;
183
type NamerOpts<T> = import("@parcel/types").Namer<T>;
184
type RuntimeOpts<T> = import("@parcel/types").Runtime<T>;
185
type ValidatorOpts = import("@parcel/types").Validator;
186
type PackagerOpts<C, B> = import("@parcel/types").Packager<C, B>;
187
type OptimizerOpts<C, B> = import("@parcel/types").Optimizer<C, B>;
188
type CompressorOpts = import("@parcel/types").Compressor;
189
type ReporterOpts = import("@parcel/types").Reporter;
190
```