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
```