0
# Module Systems
1

2
Type definitions for various JavaScript module systems and their configuration options. These types support ES6 modules, CommonJS, UMD, AMD, Node.js, and SystemJS formats with comprehensive interoperability settings.
3

4
## Capabilities
5

6
### Module Configuration Types
7

8
Core module system configuration supporting multiple output formats.
9

10
```typescript { .api }
11
/**
12
 * All supported module system configurations
13
 */
14
type ModuleConfig = 
15
  | Es6Config | CommonJsConfig | UmdConfig 
16
  | AmdConfig | NodeNextConfig | SystemjsConfig;
17

18
/**
19
 * Base configuration shared across module systems
20
 */
21
interface BaseModuleConfig {
22
  /** Non-enumerable __esModule property control */
23
  strict?: boolean;
24
  /** Emit 'use strict' directive */
25
  strictMode?: boolean;
26
  /** Lazy evaluation of imports */
27
  lazy?: boolean | string[];
28
  /** Import interoperability mode */
29
  importInterop?: "swc" | "babel" | "node" | "none";
30
  /** Output file extension */
31
  outFileExtension?: "js" | "mjs" | "cjs";
32
  /** Emit cjs-module-lexer annotations */
33
  exportInteropAnnotation?: boolean;
34
  /** Preserve dynamic imports */
35
  ignoreDynamic?: boolean;
36
  /** Allow top-level this */
37
  allowTopLevelThis?: boolean;
38
  /** Preserve import.meta */
39
  preserveImportMeta?: boolean;
40
  /** Resolve .mjs fully */
41
  resolveFully?: boolean;
42
  /** Deprecated: use importInterop instead */
43
  noInterop?: boolean;
44
}
45
```
46

47
### ES6 Modules
48

49
ECMAScript 2015+ module configuration for modern JavaScript environments.
50

51
```typescript { .api }
52
/**
53
 * ES6/ES2015+ module configuration
54
 */
55
interface Es6Config extends BaseModuleConfig {
56
  type: "es6";
57
}
58
```
59

60
**Usage Examples:**
61

62
```typescript
63
import type { Es6Config } from "@swc/types";
64

65
// Modern ES6 module output
66
const es6Config: Es6Config = {
67
  type: "es6",
68
  strict: true,
69
  strictMode: true
70
};
71

72
// ES6 with lazy loading for better performance
73
const es6LazyConfig: Es6Config = {
74
  type: "es6",
75
  lazy: true, // Lazy-load dependencies, not local imports
76
  outFileExtension: "js"
77
};
78
```
79

80
### CommonJS
81

82
CommonJS module system configuration for Node.js environments.
83

84
```typescript { .api }
85
/**
86
 * CommonJS module configuration
87
 */
88
interface CommonJsConfig extends BaseModuleConfig {
89
  type: "commonjs";
90
}
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
import type { CommonJsConfig } from "@swc/types";
97

98
// Standard CommonJS output
99
const cjsConfig: CommonJsConfig = {
100
  type: "commonjs",
101
  importInterop: "swc", // Use SWC's interop helpers
102
  strictMode: true
103
};
104

105
// Node.js native interop
106
const nodeConfig: CommonJsConfig = {
107
  type: "commonjs",
108
  importInterop: "node", // Use Node.js native import behavior
109
  outFileExtension: "cjs",
110
  exportInteropAnnotation: true // Emit cjs-module-lexer annotations
111
};
112

113
// Legacy compatibility
114
const legacyConfig: CommonJsConfig = {
115
  type: "commonjs",
116
  importInterop: "none", // No interop helpers
117
  strict: false
118
};
119
```
120

121
### UMD (Universal Module Definition)
122

123
UMD configuration for libraries that need to work in multiple environments.
124

125
```typescript { .api }
126
/**
127
 * UMD module configuration
128
 */
129
interface UmdConfig extends BaseModuleConfig {
130
  type: "umd";
131
  /** Global variable mappings for dependencies */
132
  globals?: { [key: string]: string };
133
}
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
import type { UmdConfig } from "@swc/types";
140

141
// Library UMD build
142
const umdConfig: UmdConfig = {
143
  type: "umd",
144
  globals: {
145
    "react": "React",
146
    "react-dom": "ReactDOM",
147
    "lodash": "_"
148
  },
149
  strictMode: true
150
};
151

152
// UMD with no external dependencies
153
const standaloneUmd: UmdConfig = {
154
  type: "umd",
155
  strict: true
156
};
157
```
158

159
### AMD (Asynchronous Module Definition)
160

161
AMD module configuration for RequireJS and similar loaders.
162

163
```typescript { .api }
164
/**
165
 * AMD module configuration
166
 */
167
interface AmdConfig extends BaseModuleConfig {
168
  type: "amd";
169
  /** Module ID for the AMD module */
170
  moduleId?: string;
171
}
172
```
173

174
**Usage Examples:**
175

176
```typescript
177
import type { AmdConfig } from "@swc/types";
178

179
// AMD with explicit module ID
180
const amdConfig: AmdConfig = {
181
  type: "amd",
182
  moduleId: "my-library",
183
  strictMode: true
184
};
185

186
// Anonymous AMD module
187
const anonymousAmd: AmdConfig = {
188
  type: "amd"
189
};
190
```
191

192
### Node.js Next
193

194
Node.js module configuration with modern Node.js features.
195

196
```typescript { .api }
197
/**
198
 * Node.js modern module configuration
199
 */
200
interface NodeNextConfig extends BaseModuleConfig {
201
  type: "nodenext";
202
}
203
```
204

205
**Usage Examples:**
206

207
```typescript
208
import type { NodeNextConfig } from "@swc/types";
209

210
// Modern Node.js with ES modules
211
const nodeNextConfig: NodeNextConfig = {
212
  type: "nodenext",
213
  outFileExtension: "mjs",
214
  preserveImportMeta: true,
215
  allowTopLevelThis: false
216
};
217
```
218

219
### SystemJS
220

221
SystemJS module configuration for dynamic module loading.
222

223
```typescript { .api }
224
/**
225
 * SystemJS module configuration
226
 */
227
interface SystemjsConfig {
228
  type: "systemjs";
229
  /** Allow top-level this in modules */
230
  allowTopLevelThis?: boolean;
231
}
232
```
233

234
**Usage Examples:**
235

236
```typescript
237
import type { SystemjsConfig } from "@swc/types";
238

239
// SystemJS for dynamic loading
240
const systemConfig: SystemjsConfig = {
241
  type: "systemjs",
242
  allowTopLevelThis: true
243
};
244
```
245

246
### Import Interoperability
247

248
Detailed configuration for how different module systems interact.
249

250
```typescript { .api }
251
/**
252
 * Import interoperability strategies
253
 */
254
type ImportInterop = "swc" | "babel" | "node" | "none";
255
```
256

257
**SWC/Babel Interop ("swc" | "babel"):**
258
- Adds `__esModule` property to exports
259
- Uses `_interop_require_default` helper for default imports
260
- Compatible with Babel-compiled modules
261

262
**Node.js Interop ("node"):**
263
- Follows Node.js native ESM/CommonJS interop rules
264
- Default import binds to `module.exports` value
265
- No `__esModule` property checking
266

267
**No Interop ("none"):**
268
- No interop helpers generated
269
- Assumes all modules use consistent export format
270
- Smallest output size but requires careful dependency management
271

272
**Lazy Loading Configuration:**
273

274
```typescript
275
// Lazy loading examples
276
const lazyConfig = {
277
  // Don't lazy-load any imports
278
  lazy: false,
279
  
280
  // Lazy-load dependencies but not local imports  
281
  lazy: true,
282
  
283
  // Lazy-load specific modules
284
  lazy: ["lodash", "moment", "react-router"]
285
};
286
```
287

288
**Complete Module Configuration Examples:**
289

290
```typescript
291
import type { ModuleConfig, CommonJsConfig, Es6Config } from "@swc/types";
292

293
// Production ES6 build
294
const productionEs6: Es6Config = {
295
  type: "es6",
296
  strict: true,
297
  strictMode: true,
298
  outFileExtension: "js",
299
  lazy: ["lodash", "moment"] // Lazy-load heavy dependencies
300
};
301

302
// Node.js library build
303
const nodeLibrary: CommonJsConfig = {
304
  type: "commonjs", 
305
  importInterop: "node",
306
  outFileExtension: "cjs",
307
  exportInteropAnnotation: true,
308
  strictMode: true,
309
  allowTopLevelThis: false
310
};
311

312
// Universal library build
313
const universalLibrary: UmdConfig = {
314
  type: "umd",
315
  globals: {
316
    "react": "React",
317
    "@babel/runtime": "babelRuntime"
318
  },
319
  strict: true,
320
  strictMode: true
321
};
322

323
// Development build with better debugging
324
const development: Es6Config = {
325
  type: "es6",
326
  strict: false, // More lenient for development
327
  preserveImportMeta: true,
328
  ignoreDynamic: true // Don't transform dynamic imports
329
};
330
```