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