0
# Experimental SWC CLI (swcx)
1

2
Next-generation CLI interface that automatically downloads and uses pre-built SWC binaries for optimal performance. This experimental tool provides the same functionality as the main SWC CLI but with improved performance through native binary execution.
3

4
## Capabilities
5

6
### swcx CLI Command
7

8
The experimental SWC CLI that downloads and executes optimized pre-built binaries.
9

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

13
# Supports all the same options as the main swc CLI:
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
18
-q, --quiet                   # Suppress compilation output
19
# ... and all other swc options
20
```
21

22
**Usage Examples:**
23

24
```bash
25
# Basic compilation (same as swc)
26
npx swcx src/index.ts -o lib/index.js
27

28
# Directory compilation with watch mode
29
npx swcx src -d lib --watch
30

31
# All swc CLI options are supported
32
npx swcx src -d lib --source-maps --workers 4
33
```
34

35
### Environment Configuration
36

37
Control swcx behavior through environment variables.
38

39
```typescript { .api }
40
const SWC_CLI_ENV: {
41
  /** Override the SWC core version to use */
42
  SWCX_CORE_VERSION_OVERRIDE: "SWCX_CORE_VERSION_OVERRIDE";
43
  /** Skip automatic version checking */
44
  SWCX_SKIP_CORE_VERSION_CHECK: "SWCX_SKIP_CORE_VERSION_CHECK";
45
};
46
```
47

48
**Environment Examples:**
49

50
```bash
51
# Use specific SWC version
52
SWCX_CORE_VERSION_OVERRIDE=1.3.50 npx swcx src -d lib
53

54
# Skip version checking
55
SWCX_SKIP_CORE_VERSION_CHECK=1 npx swcx src -d lib
56

57
# Combined usage
58
SWCX_CORE_VERSION_OVERRIDE=1.3.50 SWCX_SKIP_CORE_VERSION_CHECK=1 npx swcx src -d lib
59
```
60

61
### Core Version Detection
62

63
Automatically determine the appropriate SWC core version to use.
64

65
```typescript { .api }
66
/**
67
 * Determine the SWC core version to use based on project configuration
68
 * 
69
 * Priority order:
70
 * 1. SWCX_CORE_VERSION_OVERRIDE environment variable
71
 * 2. @swc/core version from local package.json dependencies
72
 * 3. Latest available version at CLI publish time
73
 * 
74
 * @returns SWC core version string
75
 */
76
function getCoreVersion(): string;
77
```
78

79
**Version Detection Logic:**
80

81
1. **Environment Override**: Uses `SWCX_CORE_VERSION_OVERRIDE` if set
82
2. **Project Dependencies**: Reads `@swc/core` version from local `package.json`
83
3. **Fallback**: Uses latest version available when CLI was published (1.3.24)
84
4. **Error Handling**: Falls back to latest version if detection fails
85

86
### Binary Management
87

88
Handle platform-specific binary downloads and execution.
89

90
```typescript { .api }
91
/**
92
 * Get the platform-specific binary name for SWC
93
 * 
94
 * Supports:
95
 * - Windows: x64, ia32, arm64 (MSVC)
96
 * - macOS: x64, arm64
97
 * - Linux: x64, arm64, arm (GNU/musl detection)
98
 * 
99
 * @returns Platform-specific binary filename
100
 * @throws Error if platform/architecture is unsupported
101
 */
102
function getBinaryName(): string;
103

104
/**
105
 * Check if the system uses musl libc (Alpine Linux, etc.)
106
 * @returns True if musl libc is detected
107
 */
108
function isMusl(): boolean;
109

110
/**
111
 * Download SWC binary and execute with provided arguments
112
 * 
113
 * Process:
114
 * 1. Determine SWC version and platform binary name
115
 * 2. Download binary from GitHub releases if not cached
116
 * 3. Cache binary in node_modules/.bin/swc-cli-{version}
117
 * 4. Execute binary with forwarded command-line arguments
118
 * 
119
 * @returns Promise resolving to spawned child process
120
 */
121
function executeBinary(): Promise<ChildProcess>;
122
```
123

124
**Binary Download Process:**
125

126
1. **Version Resolution**: Determine SWC core version to use
127
2. **Platform Detection**: Identify OS and architecture
128
3. **Binary Selection**: Choose correct binary from supported platforms
129
4. **Download**: Fetch from `https://github.com/swc-project/swc/releases/download/v{version}/{binary}`
130
5. **Caching**: Store in `node_modules/.bin/swc-cli-{version}/`
131
6. **Execution**: Spawn binary with forwarded arguments
132

133
### Platform Support
134

135
Supported platforms and architectures:
136

137
```typescript { .api }
138
type PlatformBinaryMap = {
139
  win32: {
140
    x64: "swc-win32-x64-msvc.exe";
141
    ia32: "swc-win32-ia32-msvc.exe";
142
    arm64: "swc-win32-arm64-msvc.exe";
143
  };
144
  darwin: {
145
    x64: "swc-darwin-x64";
146
    arm64: "swc-darwin-arm64";
147
  };
148
  linux: {
149
    x64: "swc-linux-x64-gnu" | "swc-linux-x64-musl";
150
    arm64: "swc-linux-arm64-gnu" | "swc-linux-arm64-musl";
151
    arm: "swc-linux-arm64-gnu";
152
  };
153
};
154
```
155

156
### Error Handling
157

158
Common error scenarios and handling:
159

160
```typescript { .api }
161
// Unsupported platform error
162
throw new Error(
163
  `Unsupported platform: binary ${binaryName} for '${platform} ${arch}' is not available`
164
);
165

166
// Version detection warnings
167
console.warn(
168
  `Failed to determine swc core version from package.json, using latest available version ${latestVersion} instead`,
169
  error
170
);
171

172
// Binary download/execution errors are handled by bin-wrapper
173
```
174

175
### Performance Benefits
176

177
swcx provides performance improvements over the main CLI:
178

179
- **Native Speed**: Direct execution of Rust-compiled binaries
180
- **Reduced Overhead**: Eliminates Node.js/JavaScript parsing overhead
181
- **Optimized Builds**: Uses production-optimized SWC binaries
182
- **Version Matching**: Automatically uses version matching your project
183
- **Caching**: Downloads binaries once and reuses them
184

185
### Migration Guide
186

187
Switching from `swc` to `swcx`:
188

189
```bash
190
# Before (traditional CLI)
191
npx swc src -d lib --watch
192

193
# After (experimental CLI)  
194
npx swcx src -d lib --watch
195

196
# All options remain the same
197
npx swcx src -d lib --source-maps --workers 4 --extensions .ts,.tsx
198
```
199

200
**Package.json Integration:**
201

202
```json
203
{
204
  "scripts": {
205
    "build": "swcx src -d lib",
206
    "build:watch": "swcx src -d lib --watch",
207
    "build:prod": "swcx src -d lib --source-maps"
208
  }
209
}
210
```
211

212
## Types
213

214
```typescript { .api }
215
type ChildProcess = import("child_process").ChildProcess;
216
type StdioOptions = import("child_process").StdioOptions;
217

218
interface PlatformBinaryMap {
219
  [platform: string]: {
220
    [arch: string]: string;
221
  };
222
}
223

224
const SWC_CLI_ENV: {
225
  SWCX_CORE_VERSION_OVERRIDE: "SWCX_CORE_VERSION_OVERRIDE";
226
  SWCX_SKIP_CORE_VERSION_CHECK: "SWCX_SKIP_CORE_VERSION_CHECK";
227
};
228
```