0
# Loaders
1
2
Built-in loaders for transforming modules during the build process, offering high-performance alternatives to traditional webpack loaders.
3
4
## Capabilities
5
6
### SWC Loader
7
8
High-performance TypeScript and JavaScript transformation using the SWC (Speedy Web Compiler) written in Rust.
9
10
```typescript { .api }
11
/** SWC loader configuration extending core SWC options */
12
interface SwcLoaderOptions {
13
/** JavaScript compilation configuration */
14
jsc?: SwcLoaderJscConfig;
15
/** Module system configuration */
16
module?: SwcLoaderModuleConfig;
17
/** Environment-specific transformations */
18
env?: SwcLoaderEnvConfig;
19
/** Treat input as module */
20
isModule?: boolean;
21
/** Rspack-specific experimental features */
22
rspackExperiments?: {
23
/** Import plugin transformations */
24
import?: any[];
25
/** Collect TypeScript AST information */
26
collectTypeScriptInfo?: boolean;
27
};
28
}
29
30
/** JavaScript compilation configuration */
31
interface SwcLoaderJscConfig {
32
/** Parser configuration */
33
parser?: SwcLoaderParserConfig;
34
/** Transform configuration */
35
transform?: SwcLoaderTransformConfig;
36
/** Target ECMAScript version */
37
target?: "es3" | "es5" | "es2015" | "es2016" | "es2017" | "es2018" | "es2019" | "es2020" | "es2021" | "es2022";
38
/** Loose mode transformations */
39
loose?: boolean;
40
/** External helpers */
41
externalHelpers?: boolean;
42
/** Keep class names */
43
keepClassNames?: boolean;
44
/** Minify configuration */
45
minify?: any;
46
/** Experimental features */
47
experimental?: any;
48
}
49
50
/** Parser configuration union type */
51
type SwcLoaderParserConfig = SwcLoaderEsParserConfig | SwcLoaderTsParserConfig;
52
53
/** ECMAScript parser configuration */
54
interface SwcLoaderEsParserConfig {
55
syntax: "ecmascript";
56
/** Enable JSX parsing */
57
jsx?: boolean;
58
/** Function bind operator */
59
functionBind?: boolean;
60
/** Decorators support */
61
decorators?: boolean;
62
/** Decorators before export */
63
decoratorsBeforeExport?: boolean;
64
/** Export default from */
65
exportDefaultFrom?: boolean;
66
/** Import assertions */
67
importAssertions?: boolean;
68
/** Private in object */
69
privateInObject?: boolean;
70
/** Allow super outside method */
71
allowSuperOutsideMethod?: boolean;
72
/** Allow return outside function */
73
allowReturnOutsideFunction?: boolean;
74
}
75
76
/** TypeScript parser configuration */
77
interface SwcLoaderTsParserConfig {
78
syntax: "typescript";
79
/** TypeScript extensions */
80
tsx?: boolean;
81
/** Decorators support */
82
decorators?: boolean;
83
/** Dynamic imports */
84
dynamicImport?: boolean;
85
}
86
87
/** Transform configuration */
88
interface SwcLoaderTransformConfig {
89
/** React JSX transform */
90
react?: {
91
/** JSX pragma */
92
pragma?: string;
93
/** JSX pragma fragment */
94
pragmaFrag?: string;
95
/** Throw if namespace is used */
96
throwIfNamespace?: boolean;
97
/** Development mode */
98
development?: boolean;
99
/** Use built-ins */
100
useBuiltins?: boolean;
101
/** Refresh */
102
refresh?: boolean;
103
/** Runtime */
104
runtime?: "automatic" | "classic";
105
/** Import source */
106
importSource?: string;
107
};
108
/** Const modules */
109
constModules?: any;
110
/** Optimizer */
111
optimizer?: any;
112
/** Legacy decorators */
113
legacyDecorator?: boolean;
114
/** Decorator metadata */
115
decoratorMetadata?: boolean;
116
}
117
118
/** Module system configuration */
119
interface SwcLoaderModuleConfig {
120
/** Module type */
121
type?: "commonjs" | "umd" | "amd" | "es6";
122
/** Strict mode */
123
strict?: boolean;
124
/** Strict mode */
125
strictMode?: boolean;
126
/** Lazy */
127
lazy?: boolean;
128
/** No interop */
129
noInterop?: boolean;
130
/** Ignore dynamic */
131
ignoreDynamic?: boolean;
132
}
133
134
/** Environment-specific transformation configuration */
135
interface SwcLoaderEnvConfig {
136
/** Target environments */
137
targets?: string | string[] | { [key: string]: string };
138
/** Core-js version */
139
coreJs?: string;
140
/** Mode */
141
mode?: "usage" | "entry";
142
/** Debug */
143
debug?: boolean;
144
/** Include */
145
include?: string[];
146
/** Exclude */
147
exclude?: string[];
148
/** Shipped proposals */
149
shippedProposals?: boolean;
150
/** For of assume array */
151
forceAllTransforms?: boolean;
152
}
153
```
154
155
**SWC Loader Usage Examples:**
156
157
```typescript
158
// Basic TypeScript configuration
159
const swcRule = {
160
test: /\.tsx?$/,
161
use: {
162
loader: "builtin:swc-loader",
163
options: {
164
jsc: {
165
parser: {
166
syntax: "typescript",
167
tsx: true,
168
decorators: true
169
},
170
transform: {
171
react: {
172
runtime: "automatic"
173
}
174
},
175
target: "es2020"
176
}
177
}
178
},
179
exclude: /node_modules/
180
};
181
182
// JavaScript with environment transformations
183
const jsRule = {
184
test: /\.jsx?$/,
185
use: {
186
loader: "builtin:swc-loader",
187
options: {
188
jsc: {
189
parser: {
190
syntax: "ecmascript",
191
jsx: true
192
},
193
transform: {
194
react: {
195
runtime: "automatic",
196
development: process.env.NODE_ENV === "development"
197
}
198
}
199
},
200
env: {
201
targets: "> 0.25%, not dead",
202
mode: "usage",
203
coreJs: "3.30"
204
}
205
}
206
}
207
};
208
209
// TypeScript with experimental features
210
const experimentalRule = {
211
test: /\.ts$/,
212
use: {
213
loader: "builtin:swc-loader",
214
options: {
215
jsc: {
216
parser: {
217
syntax: "typescript",
218
decorators: true
219
},
220
transform: {
221
legacyDecorator: true,
222
decoratorMetadata: true
223
},
224
experimental: {
225
plugins: [
226
["@swc/plugin-transform-imports", {
227
"lodash": {
228
"transform": "lodash/${member}",
229
"preventFullImport": true
230
}
231
}]
232
]
233
}
234
},
235
rspackExperiments: {
236
collectTypeScriptInfo: true
237
}
238
}
239
}
240
};
241
```
242
243
### Lightning CSS Loader
244
245
High-performance CSS transformation and processing using Lightning CSS written in Rust.
246
247
```typescript { .api }
248
/** Lightning CSS loader configuration */
249
interface LightningcssLoaderOptions {
250
/** Enable minification */
251
minify?: boolean;
252
/** Browser targets for compatibility */
253
targets?: Targets;
254
/** CSS features to include */
255
include?: Features;
256
/** CSS features to exclude */
257
exclude?: Features;
258
/** Draft CSS features */
259
drafts?: Drafts;
260
/** Non-standard CSS features */
261
nonStandard?: NonStandard;
262
/** Pseudo-class transformations */
263
pseudoClasses?: PseudoClasses;
264
/** Unused symbol removal */
265
unusedSymbols?: string[];
266
/** Error recovery mode */
267
errorRecovery?: boolean;
268
/** CSS modules configuration */
269
cssModules?: CSSModulesConfig;
270
}
271
272
/** Browser targets specification */
273
type Targets = string | string[] | BrowserTargets;
274
275
/** Specific browser version targets */
276
interface BrowserTargets {
277
/** Android browser */
278
android?: number;
279
/** Chrome */
280
chrome?: number;
281
/** Edge */
282
edge?: number;
283
/** Firefox */
284
firefox?: number;
285
/** Internet Explorer */
286
ie?: number;
287
/** iOS Safari */
288
ios_saf?: number;
289
/** Opera */
290
opera?: number;
291
/** Safari */
292
safari?: number;
293
/** Samsung Internet */
294
samsung?: number;
295
}
296
297
/** CSS feature flags */
298
interface Features {
299
/** Nesting support */
300
nesting?: boolean;
301
/** Not pseudo-class */
302
not?: boolean;
303
/** Dir pseudo-class */
304
dir?: boolean;
305
/** Lang pseudo-class */
306
lang?: boolean;
307
/** Is/where pseudo-classes */
308
is?: boolean;
309
/** Text decoration */
310
textDecoration?: boolean;
311
/** Media query ranges */
312
mediaQueryRanges?: boolean;
313
/** Custom media queries */
314
customMediaQueries?: boolean;
315
/** Clamp function */
316
clamp?: boolean;
317
/** Color function */
318
colorFunction?: boolean;
319
/** OKLCh colors */
320
oklch?: boolean;
321
/** Color mix function */
322
colorMix?: boolean;
323
/** P3 color space */
324
p3?: boolean;
325
/** Hex alpha colors */
326
hexAlphaColors?: boolean;
327
/** Space separated color notation */
328
spaceSeparatedColorNotation?: boolean;
329
/** Logical properties */
330
logicalProperties?: boolean;
331
/** Selectors level 4 */
332
selectorsL4?: boolean;
333
}
334
335
/** Draft CSS features */
336
interface Drafts {
337
/** Custom selectors */
338
customSelectors?: boolean;
339
}
340
341
/** Non-standard CSS features */
342
interface NonStandard {
343
/** Deep combinator */
344
deepSelectorCombinator?: boolean;
345
}
346
347
/** Pseudo-class transformation options */
348
interface PseudoClasses {
349
/** Hover media query replacement */
350
hover?: "hover" | "none";
351
/** Active media query replacement */
352
active?: "active" | "none";
353
/** Focus media query replacement */
354
focus?: "focus" | "none";
355
/** Focus visible media query replacement */
356
focusVisible?: "focus-visible" | "none";
357
/** Focus within media query replacement */
358
focusWithin?: "focus-within" | "none";
359
}
360
361
/** CSS Modules configuration */
362
interface CSSModulesConfig {
363
/** Pattern for generated class names */
364
pattern?: string;
365
/** Dash case class names */
366
dashCase?: boolean;
367
}
368
```
369
370
**Lightning CSS Loader Usage Examples:**
371
372
```typescript
373
// Basic CSS processing
374
const cssRule = {
375
test: /\.css$/,
376
use: [
377
"builtin:lightningcss-loader"
378
]
379
};
380
381
// CSS with minification and targets
382
const productionCssRule = {
383
test: /\.css$/,
384
use: [
385
{
386
loader: "builtin:lightningcss-loader",
387
options: {
388
minify: true,
389
targets: "> 0.25%, not dead",
390
errorRecovery: true
391
}
392
}
393
]
394
};
395
396
// Advanced CSS features
397
const modernCssRule = {
398
test: /\.css$/,
399
use: [
400
{
401
loader: "builtin:lightningcss-loader",
402
options: {
403
targets: {
404
chrome: 90,
405
firefox: 88,
406
safari: 14
407
},
408
include: {
409
nesting: true,
410
customMediaQueries: true,
411
colorFunction: true,
412
oklch: true,
413
logicalProperties: true
414
},
415
drafts: {
416
customSelectors: true
417
},
418
pseudoClasses: {
419
hover: "hover",
420
focusVisible: "focus-visible"
421
}
422
}
423
}
424
]
425
};
426
427
// CSS Modules
428
const cssModulesRule = {
429
test: /\.module\.css$/,
430
use: [
431
{
432
loader: "builtin:lightningcss-loader",
433
options: {
434
cssModules: {
435
pattern: "[name]_[local]_[hash]",
436
dashCase: true
437
}
438
}
439
}
440
]
441
};
442
443
// Browserslist integration
444
const browserslistRule = {
445
test: /\.css$/,
446
use: [
447
{
448
loader: "builtin:lightningcss-loader",
449
options: {
450
targets: "defaults", // Uses browserslist config
451
minify: process.env.NODE_ENV === "production"
452
}
453
}
454
]
455
};
456
```
457
458
### Loader Rule Configuration
459
460
Configuration patterns for using loaders within module rules.
461
462
```typescript { .api }
463
/** Module rule with loader configuration */
464
interface LoaderRule {
465
/** File pattern to match */
466
test: RegExp;
467
/** Files to include */
468
include?: string | RegExp | (string | RegExp)[];
469
/** Files to exclude */
470
exclude?: string | RegExp | (string | RegExp)[];
471
/** Loader to use */
472
use: string | LoaderConfig | (string | LoaderConfig)[];
473
/** Module type override */
474
type?: string;
475
/** Parser options */
476
parser?: any;
477
/** Generator options */
478
generator?: any;
479
}
480
481
/** Individual loader configuration */
482
interface LoaderConfig {
483
/** Loader name */
484
loader: string;
485
/** Loader options */
486
options?: any;
487
}
488
```
489
490
**Complete Loader Configuration Examples:**
491
492
```typescript
493
import type { Configuration } from "@rspack/core";
494
495
const config: Configuration = {
496
module: {
497
rules: [
498
// TypeScript/JavaScript with SWC
499
{
500
test: /\.[jt]sx?$/,
501
exclude: /node_modules/,
502
use: {
503
loader: "builtin:swc-loader",
504
options: {
505
jsc: {
506
parser: {
507
syntax: "typescript",
508
tsx: true
509
},
510
transform: {
511
react: {
512
runtime: "automatic"
513
}
514
},
515
target: "es2020"
516
},
517
env: {
518
targets: "defaults"
519
}
520
}
521
}
522
},
523
524
// CSS with Lightning CSS
525
{
526
test: /\.css$/,
527
use: [
528
"style-loader", // or CSS extract plugin
529
{
530
loader: "builtin:lightningcss-loader",
531
options: {
532
minify: true,
533
targets: "> 0.25%"
534
}
535
}
536
]
537
},
538
539
// Assets
540
{
541
test: /\.(png|jpg|jpeg|gif|svg)$/,
542
type: "asset/resource"
543
},
544
545
// Fonts
546
{
547
test: /\.(woff|woff2|eot|ttf|otf)$/,
548
type: "asset/resource"
549
}
550
]
551
}
552
};
553
554
// Environment-specific configurations
555
const developmentRules = [
556
{
557
test: /\.[jt]sx?$/,
558
exclude: /node_modules/,
559
use: {
560
loader: "builtin:swc-loader",
561
options: {
562
jsc: {
563
parser: { syntax: "typescript", tsx: true },
564
transform: {
565
react: {
566
runtime: "automatic",
567
development: true,
568
refresh: true // React Fast Refresh
569
}
570
}
571
}
572
}
573
}
574
}
575
];
576
577
const productionRules = [
578
{
579
test: /\.[jt]sx?$/,
580
exclude: /node_modules/,
581
use: {
582
loader: "builtin:swc-loader",
583
options: {
584
jsc: {
585
parser: { syntax: "typescript", tsx: true },
586
transform: {
587
react: {
588
runtime: "automatic"
589
}
590
},
591
minify: {
592
compress: true,
593
mangle: true
594
}
595
}
596
}
597
}
598
}
599
];
600
```
601
602
### Performance Considerations
603
604
Built-in loaders offer significant performance improvements over JavaScript-based alternatives:
605
606
- **SWC Loader**: 10-20x faster than Babel for TypeScript/JavaScript transformation
607
- **Lightning CSS Loader**: 100x faster than PostCSS for CSS processing
608
- **Native Integration**: Direct integration with Rspack's Rust core reduces overhead
609
- **Parallel Processing**: Multi-threaded processing for large codebases
610
- **Incremental Compilation**: Smart caching and change detection
611
612
```typescript
613
// Performance optimization example
614
const performantConfig = {
615
module: {
616
rules: [
617
{
618
test: /\.tsx?$/,
619
use: {
620
loader: "builtin:swc-loader",
621
options: {
622
// Minimal transformations for maximum speed
623
jsc: {
624
target: "es2020", // Modern target reduces transforms
625
parser: {
626
syntax: "typescript",
627
tsx: true
628
}
629
},
630
// Skip environment transforms in development
631
...(process.env.NODE_ENV === "production" && {
632
env: {
633
targets: "defaults"
634
}
635
})
636
}
637
}
638
}
639
]
640
}
641
};
642
```