0
# Configuration
1

2
Core configuration interfaces for SWC compilation, parsing, and transformation. These types define the complete configuration API for integrating with SWC.
3

4
## Capabilities
5

6
### Main Options Interface
7

8
The primary programmatic options interface extending the base Config interface.
9

10
```typescript { .api }
11
/**
12
 * Programmatic options for SWC compilation
13
 */
14
interface Options extends Config {
15
  /** If true, a file is parsed as a script instead of module */
16
  script?: boolean;
17
  /** Working directory for resolving relative paths */
18
  cwd?: string;
19
  /** Filename associated with the code being compiled */
20
  filename?: string;
21
  /** Project root directory for configuration resolution */
22
  root?: string;
23
  /** How SWC chooses its project root */
24
  rootMode?: "root" | "upward" | "upward-optional";
25
  /** Current active environment for configuration loading */
26
  envName?: string;
27
  /** Path to configuration file or boolean to disable */
28
  configFile?: string | boolean;
29
  /** Enable searching for .swcrc files */
30
  swcrc?: boolean;
31
  /** Packages considered as "root" for .swcrc loading */
32
  swcrcRoots?: boolean | MatchPattern | MatchPattern[];
33
  /** Input source map configuration */
34
  inputSourceMap?: boolean | string;
35
  /** Source file name for source maps */
36
  sourceFileName?: string;
37
  /** Source root for generated source maps */
38
  sourceRoot?: string;
39
  /** Transform plugin */
40
  plugin?: Plugin;
41
  /** Module type detection */
42
  isModule?: boolean | "unknown" | "commonjs";
43
  /** Output path for source map fixes */
44
  outputPath?: string;
45
}
46

47
interface CallerOptions {
48
  name: string;
49
  [key: string]: any;
50
}
51

52
/**
53
 * Pattern matching interface for file filtering
54
 */
55
interface MatchPattern { }
56
```
57

58
### Base Configuration Interface
59

60
The core .swcrc configuration interface used for file-based configuration.
61

62
```typescript { .api }
63
/**
64
 * .swcrc configuration interface
65
 */
66
interface Config {
67
  /** File matching patterns (regex syntax) */
68
  test?: string | string[];
69
  /** File exclusion patterns (regex syntax) */
70
  exclude?: string | string[];
71
  /** Environment-specific configuration */
72
  env?: EnvConfig;
73
  /** JavaScript compilation configuration */
74
  jsc?: JscConfig;
75
  /** Module system configuration */
76
  module?: ModuleConfig;
77
  /** Enable minification */
78
  minify?: boolean;
79
  /** Source map generation */
80
  sourceMaps?: boolean | "inline";
81
  /** Include source content in source maps */
82
  inlineSourcesContent?: boolean;
83
}
84

85
type Swcrc = Config | Config[];
86
```
87

88
### JavaScript Compilation Configuration
89

90
JavaScript-specific compilation settings including parsing, transformation, and optimization.
91

92
```typescript { .api }
93
interface JscConfig {
94
  /** Babel-compatible optimization assumptions */
95
  assumptions?: Assumptions;
96
  /** Loose transformation mode */
97
  loose?: boolean;
98
  /** Parser configuration */
99
  parser?: ParserConfig;
100
  /** Transform configuration */
101
  transform?: TransformConfig;
102
  /** Use @swc/helpers instead of inline helpers */
103
  externalHelpers?: boolean;
104
  /** ECMAScript target version */
105
  target?: JscTarget;
106
  /** Keep class names during compilation */
107
  keepClassNames?: boolean;
108
  /** Experimental features */
109
  experimental?: ExperimentalConfig;
110
  /** Base URL for module resolution */
111
  baseUrl?: string;
112
  /** Path mapping configuration */
113
  paths?: { [from: string]: string[] };
114
  /** Minification options */
115
  minify?: JsMinifyOptions;
116
  /** Preserve all comments */
117
  preserveAllComments?: boolean;
118
  /** Output character encoding */
119
  output?: { charset?: 'utf8' | 'ascii' };
120
}
121

122
interface ExperimentalConfig {
123
  /** Optimize hygiene */
124
  optimizeHygiene?: boolean;
125
  /** Keep import assertions */
126
  keepImportAssertions?: boolean;
127
  /** Emit assert for import attributes */
128
  emitAssertForImportAttributes?: boolean;
129
  /** Cache root directory */
130
  cacheRoot?: string;
131
  /** WebAssembly plugins */
132
  plugins?: WasmPlugin[];
133
  /** Run WASM plugins before TypeScript stripping */
134
  runPluginFirst?: boolean;
135
  /** Disable builtin transforms for testing */
136
  disableBuiltinTransformsForInternalTesting?: boolean;
137
  /** Emit isolated .d.ts files */
138
  emitIsolatedDts?: boolean;
139
  /** Disable all lint rules */
140
  disableAllLints?: boolean;
141
}
142
```
143

144
### Environment Configuration
145

146
Babel-preset-env compatible configuration for environment-based transformations.
147

148
```typescript { .api }
149
/**
150
 * Configuration ported from babel-preset-env
151
 */
152
interface EnvConfig {
153
  /** Polyfill mode */
154
  mode?: "usage" | "entry";
155
  /** Debug output */
156
  debug?: boolean;
157
  /** Enable dynamic import support */
158
  dynamicImport?: boolean;
159
  /** Loose transformation mode */
160
  loose?: boolean;
161
  /** Transpile broken syntax to modern syntax */
162
  bugfixes?: boolean;
163
  /** Skip ES features */
164
  skip?: string[];
165
  /** Include specific features */
166
  include?: string[];
167
  /** Exclude specific features */
168
  exclude?: string[];
169
  /** Core-js version */
170
  coreJs?: string;
171
  /** Target environments */
172
  targets?: any;
173
  /** Path to polyfills */
174
  path?: string;
175
  /** Enable shipped proposals */
176
  shippedProposals?: boolean;
177
  /** Force all transforms */
178
  forceAllTransforms?: boolean;
179
}
180
```
181

182
### Transform Configuration
183

184
Configuration for various transformation passes including React, decorators, and TypeScript.
185

186
```typescript { .api }
187
/**
188
 * Options for transform passes
189
 */
190
interface TransformConfig {
191
  /** React/JSX transformation */
192
  react?: ReactConfig;
193
  /** Constant modules configuration */
194
  constModules?: ConstModulesConfig;
195
  /** Optimizer configuration */
196
  optimizer?: OptimizerConfig;
197
  /** Legacy decorator transformation */
198
  legacyDecorator?: boolean;
199
  /** Decorator metadata emission */
200
  decoratorMetadata?: boolean;
201
  /** Decorator version */
202
  decoratorVersion?: "2021-12" | "2022-03";
203
  /** Treat const enum as enum */
204
  treatConstEnumAsEnum?: boolean;
205
  /** Use defineProperty for class fields */
206
  useDefineForClassFields?: boolean;
207
  /** Verbatim module syntax */
208
  verbatimModuleSyntax?: boolean;
209
  /** TypeScript enum mutability */
210
  tsEnumIsMutable?: boolean;
211
}
212

213
interface ReactConfig {
214
  /** JSX pragma function */
215
  pragma?: string;
216
  /** JSX fragment pragma */
217
  pragmaFrag?: string;
218
  /** Throw on XML namespaced tags */
219
  throwIfNamespace?: boolean;
220
  /** Development mode */
221
  development?: boolean;
222
  /** Use Object.assign instead of _extends */
223
  useBuiltins?: boolean;
224
  /** Fast refresh configuration */
225
  refresh?: boolean | RefreshConfig;
226
  /** JSX runtime */
227
  runtime?: "automatic" | "classic";
228
  /** Import source for jsx/jsxs factories */
229
  importSource?: string;
230
}
231

232
interface RefreshConfig {
233
  refreshReg?: string;
234
  refreshSig?: string;
235
  emitFullSignatures?: boolean;
236
}
237
```
238

239
### Optimization Configuration
240

241
Configuration for SWC's optimization passes.
242

243
```typescript { .api }
244
interface OptimizerConfig {
245
  /** Simplify expressions */
246
  simplify?: boolean;
247
  /** Global variable inlining */
248
  globals?: GlobalPassOption;
249
  /** JSON minification */
250
  jsonify?: { minCost: number };
251
}
252

253
/**
254
 * Options for inline-global pass
255
 */
256
interface GlobalPassOption {
257
  /** Global variables to inline with values */
258
  vars?: Record<string, string>;
259
  /** Environment variables to inline */
260
  envs?: string[] | Record<string, string>;
261
  /** typeof replacements */
262
  typeofs?: Record<string, string>;
263
}
264

265
/**
266
 * Constant modules configuration for Ember-style imports
267
 */
268
interface ConstModulesConfig {
269
  globals?: {
270
    [module: string]: {
271
      [name: string]: string;
272
    };
273
  };
274
}
275
```
276

277
### Plugin Interface
278

279
Interface for SWC transform plugins.
280

281
```typescript { .api }
282
/**
283
 * Transform plugin interface
284
 */
285
interface Plugin {
286
  (module: Program): Program;
287
}
288

289
type WasmPlugin = [wasmPackage: string, config: Record<string, any>];
290

291
interface WasmAnalysisOptions {
292
  parser?: ParserConfig;
293
  module?: true | false | "unknown";
294
  filename?: string;
295
  errorFormat?: "json" | "normal";
296
  cacheRoot?: string;
297
  plugins: WasmPlugin[];
298
}
299
```
300

301
**Usage Examples:**
302

303
```typescript
304
import type { Options, JscConfig } from "@swc/types";
305

306
// Basic TypeScript compilation
307
const basicConfig: Options = {
308
  jsc: {
309
    parser: {
310
      syntax: "typescript",
311
      tsx: true
312
    },
313
    target: "es2020"
314
  },
315
  module: {
316
    type: "es6"
317
  }
318
};
319

320
// Advanced configuration with optimization
321
const advancedConfig: Options = {
322
  filename: "src/app.tsx",
323
  jsc: {
324
    parser: {
325
      syntax: "typescript",
326
      tsx: true,
327
      decorators: true
328
    },
329
    target: "es2020",
330
    transform: {
331
      react: {
332
        runtime: "automatic",
333
        development: process.env.NODE_ENV === "development"
334
      },
335
      optimizer: {
336
        simplify: true,
337
        globals: {
338
          vars: {
339
            __DEV__: "false"
340
          }
341
        }
342
      }
343
    },
344
    minify: {
345
      compress: {
346
        dead_code: true,
347
        drop_console: true
348
      },
349
      mangle: true
350
    }
351
  },
352
  module: {
353
    type: "es6"
354
  },
355
  sourceMaps: true
356
};
357
```