0
# @swc/cli
1

2
@swc/cli provides command-line interface tools for SWC (Speedy Web Compiler), a super-fast TypeScript/JavaScript compiler and bundler written in Rust. The package offers comprehensive tooling for modern JavaScript development including transpilation, bundling, file watching, and integration with build systems.
3

4
## Package Information
5

6
- **Package Name**: @swc/cli
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @swc/cli`
10
- **Node Requirement**: >= 16.14.0
11

12
## Core Imports
13

14
The package provides three main CLI executables rather than library imports:
15

16
```bash
17
# Main SWC CLI for compilation
18
npx swc [options] <files...>
19

20
# Experimental binary downloader CLI
21
npx swcx [options] <files...>
22

23
# SWC bundler CLI
24
npx spack [options]
25
```
26

27
For programmatic usage:
28

29
```typescript
30
import { swcDir } from "@swc/cli";
31
```
32

33
CommonJS:
34

35
```javascript
36
const { swcDir } = require("@swc/cli");
37
```
38

39
## Basic Usage
40

41
```bash
42
# Compile a single file
43
npx swc input.ts -o output.js
44

45
# Compile directory with watch mode
46
npx swc src -d lib --watch
47

48
# Bundle with spack
49
npx spack --entry ./src/index.ts --output dist/
50

51
# Use experimental swcx CLI
52
npx swcx src -d lib
53
```
54

55
## Architecture
56

57
@swc/cli is built around three main components:
58

59
- **Main SWC CLI** (`swc`): Core compilation tool with extensive options for TypeScript/JavaScript transpilation
60
- **SWC Bundler** (`spack`): Bundling tool powered by SWC's bundling capabilities
61
- **Experimental CLI** (`swcx`): Next-generation CLI that downloads optimized binaries
62
- **Programmatic API**: Limited programmatic interface for directory compilation
63

64
## Capabilities
65

66
### Main SWC CLI Tool
67

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

70
```typescript { .api }
71
// CLI usage: npx swc [options] <files...>
72

73
// Programmatic interface
74
function swcDir(options: {
75
  cliOptions: CliOptions;
76
  swcOptions: Options;  
77
  callbacks?: Callbacks;
78
}): Promise<void>;
79

80
interface CliOptions {
81
  outDir: string;
82
  outFile: string;
83
  stripLeadingPaths: boolean;
84
  sync: boolean;
85
  workers: number | undefined;
86
  sourceMapTarget?: string;
87
  filename: string;
88
  filenames: string[];
89
  extensions: string[];
90
  watch: boolean;
91
  copyFiles: boolean;
92
  outFileExtension?: string;
93
  includeDotfiles: boolean;
94
  deleteDirOnStart: boolean;
95
  quiet: boolean;
96
  only: string[];
97
  ignore: string[];
98
}
99
```
100

101
[SWC CLI](./swc-cli.md)
102

103
### SWC Bundler
104

105
Bundling functionality that uses SWC's high-performance bundler to create optimized JavaScript bundles from TypeScript and JavaScript sources.
106

107
```typescript { .api }
108
// CLI usage: npx spack [options]
109

110
interface SpackCliOptions {
111
  debug: boolean;
112
}
113

114
// Uses @swc/core BundleOptions internally
115
```
116

117
[SWC Bundler](./spack.md)
118

119
### Experimental SWC CLI
120

121
Next-generation CLI interface that automatically downloads and uses pre-built SWC binaries for optimal performance.
122

123
```typescript { .api }
124
// CLI usage: npx swcx [options] <files...>
125

126
function getCoreVersion(): string;
127
function getBinaryName(): string;
128
function executeBinary(): Promise<ChildProcess>;
129

130
const SWC_CLI_ENV: {
131
  SWCX_CORE_VERSION_OVERRIDE: string;
132
  SWCX_SKIP_CORE_VERSION_CHECK: string;
133
};
134
```
135

136
[Experimental CLI](./swcx.md)
137

138
## Types
139

140
```typescript { .api }
141
interface Callbacks {
142
  readonly onSuccess?: (data: {
143
    duration: number;
144
    compiled?: number;
145
    copied?: number;
146
    filename?: string;
147
  }) => any;
148
  readonly onFail?: (data: {
149
    duration: number;
150
    reasons: Map<string, string>;
151
  }) => any;
152
  readonly onWatchReady?: () => any;
153
}
154

155
enum CompileStatus {
156
  Copied,
157
  Compiled,
158
  Omitted,
159
  Failed,
160
}
161

162
// Re-exports @swc/core types
163
type Options = import("@swc/core").Options;
164
type Output = import("@swc/core").Output;
165
```