0
# @parcel/transformer-css
1
2
@parcel/transformer-css is a CSS transformer plugin for the Parcel bundler that provides comprehensive CSS processing capabilities using LightningCSS. It handles CSS transformation, CSS modules support, dependency analysis, source map generation, and browser compatibility transformations with advanced features like error recovery and asset environment normalization.
3
4
## Package Information
5
6
- **Package Name**: @parcel/transformer-css
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow types)
9
- **Installation**: Automatically included with Parcel 2.x installations
10
- **Parcel Version**: ^2.15.3
11
- **Node Version**: >= 16.0.0
12
13
## Core Imports
14
15
This is a Parcel plugin that exports a configured Transformer instance and is not typically imported directly by user code. The transformer is automatically used by Parcel when processing CSS files.
16
17
```javascript
18
// For custom Parcel configurations or plugin development
19
const CSSTransformer = require("@parcel/transformer-css");
20
```
21
22
## Basic Usage
23
24
The transformer operates automatically within Parcel's build pipeline when CSS files are encountered. Configuration is provided through `.parcelrc` or package.json:
25
26
```json
27
{
28
"@parcel/transformer-css": {
29
"cssModules": {
30
"include": ["**/*.module.css"],
31
"exclude": ["**/node_modules/**"]
32
},
33
"errorRecovery": false,
34
"drafts": {},
35
"pseudoClasses": {}
36
}
37
}
38
```
39
40
## Architecture
41
42
The transformer is built around several key components:
43
44
- **LightningCSS Integration**: Uses LightningCSS for high-performance CSS parsing and transformation
45
- **CSS Modules Engine**: Configurable CSS modules processing with include/exclude patterns
46
- **Dependency Analysis**: Automatic detection and processing of CSS imports and URL dependencies
47
- **Asset Environment Normalization**: Normalizes asset environments for consistent bundling across different output formats
48
- **Source Map Integration**: Preserves and generates source maps throughout the transformation process
49
- **Error Recovery System**: Configurable error recovery with detailed diagnostic reporting
50
51
## Capabilities
52
53
### CSS Processing and Transformation
54
55
Core CSS transformation functionality that processes standard CSS files with browser compatibility transformations.
56
57
```javascript { .api }
58
/**
59
* Main CSS transformation method
60
* @param {Object} params - Transformation parameters
61
* @param {Asset} params.asset - Parcel asset to transform
62
* @param {Object} params.config - Transformer configuration
63
* @param {Object} params.options - Build options
64
* @param {Logger} params.logger - Parcel logger instance
65
* @returns {Promise<Asset[]>} Array of transformed assets
66
*/
67
async function transform({ asset, config, options, logger }): Promise<Asset[]>;
68
```
69
70
### CSS Modules Processing
71
72
Processes CSS files as CSS modules with configurable include/exclude patterns and advanced features.
73
74
```javascript { .api }
75
/**
76
* CSS Modules configuration interface
77
*/
78
interface CSSModulesConfig {
79
/** Enable CSS modules globally or with specific configuration */
80
cssModules?: boolean | {
81
/** Glob patterns for files to process as CSS modules */
82
include?: string | string[] | RegExp[];
83
/** Glob patterns for files to exclude from CSS module processing */
84
exclude?: string | string[] | RegExp[];
85
/** Process all CSS files as modules when true */
86
global?: boolean;
87
/** Support dashed identifiers in CSS modules */
88
dashedIdents?: boolean;
89
};
90
}
91
```
92
93
### Style Attribute Processing
94
95
Transforms CSS within HTML style attributes with dependency analysis.
96
97
```javascript { .api }
98
/**
99
* Processes inline CSS within HTML style attributes
100
* Uses LightningCSS transformStyleAttribute function
101
* Automatically applied when asset.meta.type === 'attr'
102
*/
103
```
104
105
### Configuration Loading
106
107
Loads and processes transformer configuration with glob pattern conversion.
108
109
```javascript { .api }
110
/**
111
* Configuration loader method
112
* @param {Object} params - Configuration parameters
113
* @param {Config} params.config - Parcel config instance
114
* @param {Object} params.options - Build options
115
* @returns {Promise<Object>} Processed configuration
116
*/
117
async function loadConfig({ config, options }): Promise<Object>;
118
```
119
120
### Dependency Analysis
121
122
Automatically detects and processes CSS imports and URL dependencies.
123
124
```javascript { .api }
125
/**
126
* Dependency types handled by the transformer
127
*/
128
interface CSSDependency {
129
type: 'import' | 'url';
130
url: string;
131
loc: SourceLocation;
132
media?: string;
133
placeholder?: string;
134
}
135
```
136
137
### Browser Target Configuration
138
139
Converts browserslist configurations to LightningCSS targets with caching.
140
141
```javascript { .api }
142
/**
143
* Converts browserslist to LightningCSS targets
144
* @param {string} browsers - Browserslist query string
145
* @returns {Object|undefined} LightningCSS targets or undefined
146
*/
147
function getTargets(browsers: string): Object | undefined;
148
```
149
150
### Source Location Conversion
151
152
Converts between LightningCSS and Parcel source location formats.
153
154
```javascript { .api }
155
/**
156
* Source location interfaces
157
*/
158
interface SourceLocation {
159
filePath: string;
160
start: { line: number; column: number };
161
end: { line: number; column: number };
162
}
163
164
/**
165
* Converts LightningCSS source location to Parcel format
166
* @param {LightningSourceLocation} loc - LightningCSS source location
167
* @returns {SourceLocation} Parcel source location
168
*/
169
function convertLoc(loc: LightningSourceLocation): SourceLocation;
170
```
171
172
## Configuration Options
173
174
### CSS Modules Configuration
175
176
```javascript { .api }
177
interface CSSModulesOptions {
178
/** Enable CSS modules processing (boolean or detailed config) */
179
cssModules?: boolean | {
180
/** Files to include as CSS modules (glob patterns or RegExp) */
181
include?: string | string[] | RegExp[];
182
/** Files to exclude from CSS modules (glob patterns or RegExp) */
183
exclude?: string | string[] | RegExp[];
184
/** Enable CSS modules globally */
185
global?: boolean;
186
/** Support dashed identifiers */
187
dashedIdents?: boolean;
188
};
189
}
190
```
191
192
### CSS Processing Options
193
194
```javascript { .api }
195
interface CSSProcessingOptions {
196
/** Enable error recovery during CSS parsing */
197
errorRecovery?: boolean;
198
/** CSS draft features configuration */
199
drafts?: Object;
200
/** CSS pseudo-classes configuration */
201
pseudoClasses?: Object;
202
}
203
```
204
205
## Error Handling
206
207
### Diagnostic Integration
208
209
The transformer integrates with Parcel's diagnostic system for comprehensive error reporting.
210
211
```javascript { .api }
212
/**
213
* Error handling with diagnostic conversion
214
* Automatically converts LightningCSS errors to Parcel diagnostics
215
* Provides helpful hints for common issues like ambiguous URLs
216
*/
217
interface DiagnosticError {
218
message: string;
219
filePath: string;
220
codeFrames?: CodeFrame[];
221
hints?: string[];
222
documentationURL?: string;
223
}
224
225
interface CodeFrame {
226
filePath: string;
227
codeHighlights: CodeHighlight[];
228
}
229
230
interface CodeHighlight {
231
start: { line: number; column: number };
232
end: { line: number; column: number };
233
}
234
```
235
236
### Warning Processing
237
238
Processes and logs LightningCSS warnings with source location information.
239
240
```javascript { .api }
241
/**
242
* Warning interface from LightningCSS
243
*/
244
interface LightningWarning {
245
message: string;
246
loc: {
247
line: number;
248
column: number;
249
};
250
}
251
```
252
253
## Asset Types
254
255
### Supported Asset Types
256
257
The transformer handles multiple types of CSS assets based on metadata:
258
259
```javascript { .api }
260
/**
261
* Asset types processed by the transformer
262
*/
263
type AssetType =
264
| 'default' // Standard CSS files
265
| 'module' // CSS module files
266
| 'attr' // CSS within HTML style attributes
267
| 'tag'; // CSS within tagged templates
268
```
269
270
### Asset Environment Normalization
271
272
Normalizes asset environments for consistent bundling across different output formats.
273
274
```javascript { .api }
275
/**
276
* Normalized asset environment properties
277
*/
278
interface NormalizedEnvironment {
279
context: 'browser' | 'react-client';
280
engines: {
281
browsers: string;
282
};
283
shouldOptimize: boolean;
284
shouldScopeHoist: boolean;
285
sourceMap: boolean;
286
}
287
```
288
289
## Dependencies
290
291
### Core Dependencies
292
293
```javascript { .api }
294
/**
295
* Key dependencies used by the transformer
296
*/
297
interface TransformerDependencies {
298
/** LightningCSS for CSS processing */
299
lightningcss: {
300
transform: Function;
301
transformStyleAttribute: Function;
302
browserslistToTargets: Function;
303
};
304
/** Parcel utilities */
305
'@parcel/utils': {
306
remapSourceLocation: Function;
307
relativePath: Function;
308
globToRegex: Function;
309
normalizeSeparators: Function;
310
};
311
/** Browserslist for browser targeting */
312
browserslist: Function;
313
}
314
```
315
316
### Parcel Core Types
317
318
```javascript { .api }
319
/**
320
* Core Parcel types used by the transformer
321
* These are simplified interfaces - full definitions are in @parcel/* packages
322
*/
323
interface Asset {
324
filePath: string;
325
env: AssetEnvironment;
326
meta: AssetMeta;
327
setBuffer(buffer: Buffer): void;
328
getBuffer(): Promise<Buffer>;
329
getMap(): Promise<SourceMap | undefined>;
330
addDependency(dependency: DependencyOptions): void;
331
addURLDependency(url: string, options?: URLDependencyOptions): void;
332
symbols: SymbolMap;
333
uniqueKey?: string;
334
isSource: boolean;
335
}
336
337
interface AssetEnvironment {
338
context: string;
339
outputFormat: string;
340
engines: { browsers: string };
341
shouldOptimize: boolean;
342
shouldScopeHoist: boolean;
343
sourceMap: boolean;
344
}
345
346
interface AssetMeta {
347
type?: string;
348
cssModulesCompiled?: boolean;
349
hasDependencies?: boolean;
350
hasReferences?: boolean;
351
}
352
353
interface DependencyOptions {
354
specifier: string;
355
specifierType: string;
356
loc?: SourceLocation;
357
packageConditions?: string[];
358
symbols?: Map<string, Symbol>;
359
meta?: object;
360
env?: object;
361
}
362
```