0
# Asset System
1

2
The Parcel Asset System is an extensible framework for processing different file types during the build process. Each asset type handles parsing, dependency collection, transformation, and code generation for specific file formats.
3

4
## Capabilities
5

6
### Base Asset Class
7

8
The foundation class that all asset types extend, providing common functionality for file processing.
9

10
```javascript { .api }
11
/**
12
 * Base Asset class for all file types
13
 * @param name - Absolute file path
14
 * @param options - Asset processing options
15
 */
16
class Asset {
17
  constructor(name, options);
18
  
19
  /** Load file contents from disk */
20
  load();
21
  
22
  /** Parse file contents into AST or structured data */
23
  parse(code);
24
  
25
  /** Extract dependencies from parsed content */
26
  collectDependencies();
27
  
28
  /** Apply transformations to the asset */
29
  transform();
30
  
31
  /** Generate output code for different targets */
32
  generate();
33
  
34
  /** Add a dependency to this asset */
35
  addDependency(name, opts);
36
  
37
  /** Check if asset might have dependencies */
38
  mightHaveDependencies();
39
  
40
  /** Determine if asset should be invalidated */
41
  shouldInvalidate(cacheData);
42
}
43
```
44

45
**Usage Examples:**
46

47
```javascript
48
// Create custom asset type
49
class CustomAsset extends Asset {
50
  async parse(code) {
51
    // Parse the file contents
52
    return customParser(code);
53
  }
54
  
55
  collectDependencies() {
56
    // Extract dependencies from AST
57
    this.addDependency('./helper.js');
58
  }
59
  
60
  generate() {
61
    // Generate output code
62
    return { js: this.generateJS() };
63
  }
64
}
65

66
// Register custom asset type
67
bundler.addAssetType('.custom', CustomAsset);
68
```
69

70
### Asset Properties
71

72
Core properties available on all Asset instances:
73

74
```javascript { .api }
75
interface AssetProperties {
76
  /** Unique asset identifier */
77
  id: string | null;
78
  
79
  /** Absolute file path */
80
  name: string;
81
  
82
  /** Base filename */
83
  basename: string;
84
  
85
  /** Path relative to project root */
86
  relativeName: string;
87
  
88
  /** File extension without dot */
89
  type: string;
90
  
91
  /** Raw file contents */
92
  contents: string | Buffer | null;
93
  
94
  /** Parsed AST or structured data */
95
  ast: any;
96
  
97
  /** Generated outputs by type */
98
  generated: { [type: string]: any } | null;
99
  
100
  /** Content hash for caching */
101
  hash: string | null;
102
  
103
  /** Source maps */
104
  sourceMaps: any;
105
  
106
  /** Asset dependencies */
107
  dependencies: Map<string, any>;
108
  
109
  /** Resolved dependency assets */
110
  depAssets: Map<string, Asset>;
111
  
112
  /** Bundle containing this asset */
113
  parentBundle: Bundle | null;
114
  
115
  /** All bundles containing this asset */
116
  bundles: Set<Bundle>;
117
  
118
  /** Build timing information */
119
  startTime: number;
120
  endTime: number;
121
  buildTime: number;
122
  
123
  /** Bundle size information */
124
  bundledSize: number;
125
}
126
```
127

128
## JavaScript Assets
129

130
### JSAsset Class
131

132
Processes JavaScript files with Babel transformations, dependency extraction, and code generation.
133

134
```javascript { .api }
135
/**
136
 * JavaScript asset processor with Babel support
137
 * Handles: .js, .jsx, .es6, .jsm, .mjs files
138
 */
139
class JSAsset extends Asset {
140
  /** Parse JavaScript code into Babel AST */
141
  parse(code);
142
  
143
  /** Extract imports, requires, and dynamic imports */
144
  collectDependencies();
145
  
146
  /** Apply Babel transforms and optimizations */
147
  transform();
148
  
149
  /** Generate JavaScript output with source maps */
150
  generate();
151
  
152
  /** Check if code might contain dependencies */
153
  mightHaveDependencies();
154
}
155
```
156

157
**Features:**
158
- ES6+ syntax transformation via Babel
159
- CommonJS and ES modules support
160
- Dynamic import code splitting
161
- Environment variable injection
162
- Global variable handling
163
- Tree shaking preparation
164

165
### TypeScriptAsset Class
166

167
Processes TypeScript files with type checking and compilation.
168

169
```javascript { .api }
170
/**
171
 * TypeScript asset processor
172
 * Handles: .ts, .tsx files
173
 */
174
class TypeScriptAsset extends Asset {
175
  /** Parse TypeScript code with type information */
176
  parse(code);
177
  
178
  /** Apply TypeScript compiler transformations */
179
  transform();
180
  
181
  /** Generate JavaScript output from TypeScript */
182
  generate();
183
}
184
```
185

186
**Features:**
187
- TypeScript compilation to JavaScript
188
- Type checking (configurable)
189
- JSX support in .tsx files
190
- Source map generation
191
- tsconfig.json configuration support
192

193
### Other JavaScript Variants
194

195
```javascript { .api }
196
/** CoffeeScript asset processor (.coffee) */
197
class CoffeeScriptAsset extends Asset;
198

199
/** Vue Single File Component processor (.vue) */
200
class VueAsset extends Asset;
201

202
/** ReasonML asset processor (.ml, .re) */
203
class ReasonAsset extends Asset;
204

205
/** Elm asset processor (.elm) */
206
class ElmAsset extends Asset;
207

208
/** Kotlin asset processor (.kt) */
209
class KotlinAsset extends Asset;
210

211
/** Rust asset processor (.rs) */
212
class RustAsset extends Asset;
213
```
214

215
## Stylesheet Assets
216

217
### CSSAsset Class
218

219
Processes CSS files with PostCSS transformations and dependency resolution.
220

221
```javascript { .api }
222
/**
223
 * CSS asset processor with PostCSS support
224
 * Handles: .css, .pcss, .postcss files
225
 */
226
class CSSAsset extends Asset {
227
  /** Parse CSS with PostCSS */
228
  parse(code);
229
  
230
  /** Extract @import and url() dependencies */
231
  collectDependencies();
232
  
233
  /** Apply PostCSS plugins and transformations */
234
  transform();
235
  
236
  /** Generate CSS output with source maps */
237
  generate();
238
}
239
```
240

241
**Features:**
242
- PostCSS plugin system
243
- CSS imports resolution
244
- URL rewriting for assets
245
- Source map support
246
- CSS Modules support
247
- Autoprefixer integration
248

249
### Preprocessor Assets
250

251
```javascript { .api }
252
/** Sass/SCSS asset processor (.sass, .scss) */
253
class SASSAsset extends Asset {
254
  /** Compile Sass to CSS using node-sass or Dart Sass */
255
  transform();
256
}
257

258
/** Less asset processor (.less) */
259
class LESSAsset extends Asset {
260
  /** Compile Less to CSS */
261
  transform();
262
}
263

264
/** Stylus asset processor (.styl, .stylus) */
265
class StylusAsset extends Asset {
266
  /** Compile Stylus to CSS */
267
  transform();
268
}
269

270
/** SugarSS asset processor (.sss) */
271
class SSSAsset extends Asset {
272
  /** Process SugarSS syntax to CSS */
273
  transform();
274
}
275
```
276

277
## Markup Assets
278

279
### HTMLAsset Class
280

281
Processes HTML files with dependency extraction and template processing.
282

283
```javascript { .api }
284
/**
285
 * HTML asset processor
286
 * Handles: .html, .htm files
287
 */
288
class HTMLAsset extends Asset {
289
  /** Parse HTML using PostHTML */
290
  parse(code);
291
  
292
  /** Extract script, link, img, and other asset references */
293
  collectDependencies();
294
  
295
  /** Apply PostHTML transforms */
296
  transform();
297
  
298
  /** Generate HTML output */
299
  generate();
300
}
301
```
302

303
**Features:**
304
- Script and stylesheet injection
305
- Asset URL rewriting
306
- Image optimization integration
307
- Template variable substitution
308
- PostHTML plugin support
309

310
### Template Assets
311

312
```javascript { .api }
313
/** Pug template processor (.jade, .pug) */
314
class PugAsset extends Asset {
315
  /** Compile Pug templates to HTML */
316
  transform();
317
}
318
```
319

320
## Data Format Assets
321

322
### JSON Assets
323

324
```javascript { .api }
325
/** JSON asset processor (.json, .json5) */
326
class JSONAsset extends Asset {
327
  /** Parse JSON/JSON5 data */
328
  parse(code);
329
  
330
  /** Generate JavaScript module from JSON */
331
  generate();
332
}
333

334
/** JSON-LD asset processor (.jsonld) */
335
class JSONLDAsset extends Asset;
336
```
337

338
### Configuration Assets
339

340
```javascript { .api }
341
/** YAML asset processor (.yaml, .yml) */
342
class YAMLAsset extends Asset {
343
  /** Parse YAML and convert to JavaScript */
344
  parse(code);
345
}
346

347
/** TOML asset processor (.toml) */
348
class TOMLAsset extends Asset {
349
  /** Parse TOML and convert to JavaScript */
350
  parse(code);
351
}
352
```
353

354
## Specialized Assets
355

356
### GraphQL Assets
357

358
```javascript { .api }
359
/** GraphQL asset processor (.gql, .graphql) */
360
class GraphqlAsset extends Asset {
361
  /** Parse GraphQL queries and schemas */
362
  parse(code);
363
  
364
  /** Generate JavaScript modules from GraphQL */
365
  generate();
366
}
367
```
368

369
### Shader Assets
370

371
```javascript { .api }
372
/** GLSL shader processor (.glsl, .vert, .frag) */
373
class GLSLAsset extends Asset {
374
  /** Process GLSL shaders */
375
  parse(code);
376
  
377
  /** Generate string modules for shaders */
378
  generate();
379
}
380
```
381

382
### WebAssembly Assets
383

384
```javascript { .api }
385
/** WebAssembly processor (.wasm) */
386
class WASMAsset extends Asset {
387
  /** Load and optimize WASM binary */
388
  load();
389
  
390
  /** Generate loader code for WASM */
391
  generate();
392
}
393
```
394

395
### Raw Assets
396

397
```javascript { .api }
398
/** Raw file processor (fallback for unknown types) */
399
class RawAsset extends Asset {
400
  /** Copy files without processing */
401
  generate();
402
}
403

404
/** Glob pattern processor */
405
class GlobAsset extends Asset {
406
  /** Resolve glob patterns to file dependencies */
407
  collectDependencies();
408
}
409
```
410

411
## Asset Registration
412

413
### Built-in Asset Types
414

415
Parcel includes built-in support for these file extensions:
416

417
```javascript { .api }
418
// JavaScript and variants
419
'.js', '.jsx', '.es6', '.jsm', '.mjs'  // JSAsset
420
'.ts', '.tsx'                          // TypeScriptAsset
421
'.coffee'                              // CoffeeScriptAsset
422
'.vue'                                 // VueAsset
423
'.re', '.ml'                           // ReasonAsset
424
'.elm'                                 // ElmAsset
425
'.kt'                                  // KotlinAsset
426
'.rs'                                  // RustAsset
427

428
// Stylesheets
429
'.css', '.pcss', '.postcss'            // CSSAsset
430
'.sass', '.scss'                       // SASSAsset
431
'.less'                                // LESSAsset
432
'.styl', '.stylus'                     // StylusAsset
433
'.sss'                                 // SSSAsset
434

435
// Markup
436
'.html', '.htm'                        // HTMLAsset
437
'.pug', '.jade'                        // PugAsset
438

439
// Data formats
440
'.json', '.json5'                      // JSONAsset
441
'.jsonld'                              // JSONLDAsset
442
'.yaml', '.yml'                        // YAMLAsset
443
'.toml'                                // TOMLAsset
444

445
// Specialized
446
'.gql', '.graphql'                     // GraphqlAsset
447
'.glsl', '.vert', '.frag'             // GLSLAsset
448
'.webmanifest'                         // WebManifestAsset
449

450
// Binary and raw
451
'.wasm'                                // WASMAsset
452
// All other extensions               // RawAsset (fallback)
453
```
454

455
### Custom Asset Registration
456

457
```javascript { .api }
458
/**
459
 * Register custom asset type
460
 * @param extension - File extension including dot
461
 * @param AssetClass - Asset class or module path
462
 */
463
bundler.addAssetType(extension, AssetClass)
464
```
465

466
**Usage Examples:**
467

468
```javascript
469
// Register custom asset class
470
class ProtobufAsset extends Asset {
471
  async parse(code) {
472
    return protobuf.parse(code);
473
  }
474
  
475
  generate() {
476
    return { js: this.generateProtobufModule() };
477
  }
478
}
479

480
bundler.addAssetType('.proto', ProtobufAsset);
481

482
// Register by module path
483
bundler.addAssetType('.custom', require.resolve('./CustomAsset'));
484

485
// Register multiple extensions
486
bundler.addAssetType('.data', DataAsset);
487
bundler.addAssetType('.config', DataAsset);
488
```
489

490
## Asset Processing Pipeline
491

492
### Processing Lifecycle
493

494
1. **Load**: Read file contents from disk
495
2. **Parse**: Convert contents to AST or structured data
496
3. **Collect Dependencies**: Extract import/require statements
497
4. **Transform**: Apply language-specific transformations
498
5. **Generate**: Produce output code for target environment
499

500
### Dependency Types
501

502
Assets can declare different types of dependencies:
503

504
```javascript { .api }
505
/**
506
 * Add dependency to asset
507
 * @param name - Module name or file path
508
 * @param opts - Dependency options
509
 */
510
addDependency(name, opts = {})
511

512
// Options:
513
interface DependencyOptions {
514
  /** Resolved dependency name */
515
  name?: string;
516
  
517
  /** Dynamic import (code splitting) */
518
  dynamic?: boolean;
519
  
520
  /** Optional dependency */
521
  optional?: boolean;
522
  
523
  /** Import location in source */
524
  loc?: SourceLocation;
525
  
526
  /** Parent asset */
527
  parent?: string;
528
  
529
  /** Environment-specific dependency */
530
  env?: string;
531
}
532
```
533

534
**Usage Examples:**
535

536
```javascript
537
// Static import
538
this.addDependency('./module.js');
539

540
// Dynamic import (code splitting)
541
this.addDependency('./lazy-module.js', { dynamic: true });
542

543
// Optional dependency
544
this.addDependency('optional-plugin', { optional: true });
545

546
// Environment-specific
547
this.addDependency('node-specific', { env: 'node' });
548
```
549

550
## Caching and Performance
551

552
### Asset Caching
553

554
Assets implement caching for improved build performance:
555

556
```javascript { .api }
557
interface AssetCaching {
558
  /** Cache invalidation check */
559
  shouldInvalidate(cacheData): boolean;
560
  
561
  /** Cache data for persistence */
562
  cacheData: { [key: string]: any };
563
  
564
  /** Content hash for change detection */
565
  hash: string | null;
566
}
567
```
568

569
### Build Timing
570

571
Assets track build performance metrics:
572

573
```javascript { .api }
574
interface AssetTiming {
575
  startTime: number;    // Build start timestamp
576
  endTime: number;      // Build end timestamp
577
  buildTime: number;    // Total build time in ms
578
  bundledSize: number;  // Final bundled size in bytes
579
}
580
```