0
# SWC CLI
1

2
Core compilation functionality for transforming TypeScript and JavaScript files with extensive configuration options, watch mode, and parallel processing.
3

4
## Capabilities
5

6
### Main CLI Command
7

8
The primary SWC compilation command with comprehensive options for file transformation.
9

10
```bash { .api }
11
npx swc [options] <files...>
12

13
# Key Options:
14
-d, --out-dir [out]           # Compile to output directory
15
-o, --out-file [out]          # Compile to single output file  
16
-w, --watch                   # Watch for file changes
17
-s, --source-maps [type]      # Generate source maps (true|false|inline|both)
18
-q, --quiet                   # Suppress compilation output
19
--sync                        # Use synchronous compilation
20
--workers [number]            # Number of parallel workers
21
-C, --config <config>         # Override config from .swcrc
22
--config-file [path]          # Path to .swcrc file
23
--extensions [list]           # File extensions to compile
24
--ignore [list]               # Glob patterns to ignore
25
--only [list]                 # Glob patterns to include only
26
--copy-files                  # Copy non-compilable files
27
--include-dotfiles            # Include dotfiles in compilation
28
--strip-leading-paths         # Remove leading directory paths
29
--delete-dir-on-start         # Clean output directory before compilation
30
--out-file-extension [ext]    # Use specific output file extension
31
```
32

33
**Usage Examples:**
34

35
```bash
36
# Basic compilation
37
npx swc src/index.ts -o lib/index.js
38

39
# Directory compilation with source maps
40
npx swc src -d lib --source-maps
41

42
# Watch mode with workers
43
npx swc src -d lib --watch --workers 4
44

45
# Custom extensions and ignore patterns
46
npx swc src -d lib --extensions .ts,.tsx --ignore "**/*.test.ts"
47

48
# Override config
49
npx swc src -d lib -C module.type=commonjs -C jsc.target=es2018
50
```
51

52
### Programmatic API
53

54
Direct programmatic access to directory compilation functionality.
55

56
```typescript { .api }
57
/**
58
 * Compile a directory of files using SWC
59
 * @param options - Configuration object containing CLI and SWC options
60
 * @returns Promise that resolves when compilation completes
61
 */
62
function swcDir(options: {
63
  cliOptions: CliOptions;
64
  swcOptions: Options;
65
  callbacks?: Callbacks;
66
}): Promise<void>;
67

68
interface CliOptions {
69
  /** Output directory path */
70
  readonly outDir: string;
71
  /** Output file path for single file compilation */
72
  readonly outFile: string;
73
  /** Remove leading directory paths in output */
74
  readonly stripLeadingPaths: boolean;
75
  /** Use synchronous compilation (useful for debugging) */
76
  readonly sync: boolean;
77
  /** Number of parallel workers (undefined for default) */
78
  readonly workers: number | undefined;
79
  /** Source map target file name */
80
  readonly sourceMapTarget?: string;
81
  /** Input filename for stdin compilation */
82
  readonly filename: string;
83
  /** Array of input file patterns */
84
  readonly filenames: string[];
85
  /** File extensions to compile */
86
  readonly extensions: string[];
87
  /** Enable watch mode */
88
  readonly watch: boolean;
89
  /** Copy non-compilable files to output */
90
  readonly copyFiles: boolean;
91
  /** Custom output file extension */
92
  readonly outFileExtension?: string;
93
  /** Include dotfiles in compilation */
94
  readonly includeDotfiles: boolean;
95
  /** Delete output directory before compilation */
96
  readonly deleteDirOnStart: boolean;
97
  /** Suppress compilation output */
98
  readonly quiet: boolean;
99
  /** Glob patterns to include only */
100
  readonly only: string[];
101
  /** Glob patterns to ignore */
102
  readonly ignore: string[];
103
}
104

105
interface Callbacks {
106
  /** Called on successful compilation */
107
  readonly onSuccess?: (data: {
108
    duration: number;
109
    compiled?: number;
110
    copied?: number;
111
    filename?: string;
112
  }) => any;
113
  /** Called on compilation failure */
114
  readonly onFail?: (data: {
115
    duration: number;
116
    reasons: Map<string, string>;
117
  }) => any;
118
  /** Called when watch mode is ready */
119
  readonly onWatchReady?: () => any;
120
}
121
```
122

123
**Usage Example:**
124

125
```typescript
126
import { swcDir } from "@swc/cli";
127

128
await swcDir({
129
  cliOptions: {
130
    outDir: "lib",
131
    outFile: "",
132
    stripLeadingPaths: false,
133
    sync: false,
134
    workers: undefined,
135
    filename: "",
136
    filenames: ["src"],
137
    extensions: [".ts", ".tsx", ".js", ".jsx"],
138
    watch: false,
139
    copyFiles: true,
140
    includeDotfiles: false,
141
    deleteDirOnStart: true,
142
    quiet: false,
143
    only: [],
144
    ignore: ["**/*.test.ts"],
145
  },
146
  swcOptions: {
147
    jsc: {
148
      target: "es2018",
149
      parser: {
150
        syntax: "typescript",
151
      },
152
    },
153
    module: {
154
      type: "commonjs",
155
    },
156
    sourceMaps: true,
157
  },
158
  callbacks: {
159
    onSuccess: ({ duration, compiled, copied }) => {
160
      console.log(`Compiled ${compiled} files in ${duration}ms`);
161
    },
162
    onFail: ({ duration, reasons }) => {
163
      console.error(`Compilation failed after ${duration}ms`);
164
      for (const [file, reason] of reasons) {
165
        console.error(`${file}: ${reason}`);
166
      }
167
    },
168
  },
169
});
170
```
171

172
### Options Parsing
173

174
Parse command-line arguments into structured options.
175

176
```typescript { .api }
177
/**
178
 * Initialize the CLI program with all available options
179
 */
180
function initProgram(): void;
181

182
/**
183
 * Parse command-line arguments into CLI and SWC options
184
 * @param args - Command-line arguments array
185
 * @returns Parsed options or undefined on error
186
 */
187
function parseArgs(args: string[]): {
188
  swcOptions: Options;
189
  cliOptions: CliOptions;
190
} | undefined;
191

192
/** Default file extensions supported by SWC */
193
const DEFAULT_EXTENSIONS: string[] = [
194
  ".js", ".jsx", ".es6", ".es", ".mjs", 
195
  ".ts", ".tsx", ".cts", ".mts"
196
];
197
```
198

199
### Utility Functions
200

201
Helper functions for file operations and compilation tasks.
202

203
```typescript { .api }
204
/**
205
 * Check if a file or directory exists
206
 * @param path - Path to check
207
 * @returns Promise resolving to existence boolean
208
 */
209
function exists(path: string): Promise<boolean>;
210

211
/**
212
 * Transform source code using SWC
213
 * @param filename - Source filename
214
 * @param code - Source code string
215
 * @param opts - SWC transformation options
216
 * @param sync - Use synchronous transformation
217
 * @param outputPath - Optional output path
218
 * @returns Promise resolving to transformation result
219
 */
220
function transform(
221
  filename: string,
222
  code: string,
223
  opts: Options,
224
  sync: boolean,
225
  outputPath: string | undefined
226
): Promise<Output>;
227

228
/**
229
 * Compile a file using SWC
230
 * @param filename - Input filename
231
 * @param opts - SWC compilation options
232
 * @param sync - Use synchronous compilation
233
 * @param outputPath - Optional output path
234
 * @returns Promise resolving to compilation result or void if ignored
235
 */
236
function compile(
237
  filename: string,
238
  opts: Options,
239
  sync: boolean,
240
  outputPath: string | undefined
241
): Promise<Output | void>;
242

243
/**
244
 * Write compiled output to file with optional source maps
245
 * @param output - SWC compilation output
246
 * @param filename - Output filename
247
 * @param sourceMaps - Source map configuration
248
 */
249
function outputFile(
250
  output: Output,
251
  filename: string,
252
  sourceMaps: undefined | Options["sourceMaps"]
253
): void;
254

255
/**
256
 * Get destination path for compiled file
257
 * @param filename - Source filename
258
 * @param outDir - Output directory
259
 * @param stripLeadingPaths - Remove leading paths
260
 * @param ext - Optional file extension override
261
 * @returns Destination file path
262
 */
263
function getDest(
264
  filename: string,
265
  outDir: string,
266
  stripLeadingPaths: boolean,
267
  ext?: string
268
): string;
269

270
/**
271
 * Map TypeScript extensions to JavaScript extensions
272
 * @param filename - Input filename
273
 * @returns JavaScript file extension
274
 */
275
function mapTsExt(filename: string): string;
276
```
277

278
### File Discovery
279

280
Functions for finding and filtering source files.
281

282
```typescript { .api }
283
/**
284
 * Find all input files based on source globs
285
 * @param sources - Array of source patterns
286
 * @param only - Glob patterns to include only
287
 * @param ignore - Glob patterns to ignore
288
 * @param includeDotfiles - Include dotfiles in results
289
 * @returns Promise resolving to array of matching files
290
 */
291
function globSources(
292
  sources: string[],
293
  only: string[],
294
  ignore: string[],
295
  includeDotfiles?: boolean
296
): Promise<string[]>;
297

298
/**
299
 * Test if filename has a compilable extension
300
 * @param filename - Filename to test
301
 * @param allowedExtension - Array of allowed extensions
302
 * @returns True if filename is compilable
303
 */
304
function isCompilableExtension(
305
  filename: string,
306
  allowedExtension: string[]
307
): boolean;
308

309
/**
310
 * Split file list into compilable and copyable files
311
 * @param files - Array of file paths
312
 * @param allowedExtension - Array of compilable extensions
313
 * @param copyFiles - Whether to include copyable files
314
 * @returns Tuple of [compilable files, copyable files]
315
 */
316
function splitCompilableAndCopyable(
317
  files: string[],
318
  allowedExtension: string[],
319
  copyFiles: boolean
320
): [compilable: string[], copyable: string[]];
321

322
/**
323
 * Set up file watching for source files
324
 * @param sources - Array of source patterns to watch
325
 * @param includeDotfiles - Include dotfiles in watching
326
 * @param only - Glob patterns to include only
327
 * @param ignore - Glob patterns to ignore
328
 * @returns Promise resolving to chokidar watcher instance
329
 */
330
function watchSources(
331
  sources: string[],
332
  includeDotfiles?: boolean,
333
  only?: string[],
334
  ignore?: string[]
335
): Promise<import("chokidar").FSWatcher>;
336
```
337

338
## Types
339

340
```typescript { .api }
341
enum CompileStatus {
342
  Copied,
343
  Compiled,
344
  Omitted,
345
  Failed,
346
}
347

348
// Re-exported from @swc/core
349
type Options = import("@swc/core").Options;
350
type Output = import("@swc/core").Output;
351
```