0
# CLI and Tools
1

2
Sucrase provides command-line tools for batch file transformation, project compilation, and development workflows. The CLI is ideal for build scripts, CI/CD pipelines, and one-off transformations.
3

4
## Capabilities
5

6
### Main CLI Tool
7

8
The primary `sucrase` command provides comprehensive file transformation capabilities with extensive configuration options.
9

10
```bash
11
sucrase [options] <srcDir>
12
```
13

14
**Basic Usage:**
15

16
```bash
17
# Transform TypeScript files
18
sucrase -t typescript -d dist src
19

20
# Transform React TypeScript files  
21
sucrase -t typescript,jsx -d build src
22

23
# Transform with custom JSX runtime
24
sucrase -t typescript,jsx --jsx-runtime automatic -d dist src
25

26
# Transform specific project
27
sucrase -p ./tsconfig.json
28
```
29

30
### CLI Options
31

32
**Required Options:**
33
- `-d, --out-dir <out>` - Output directory for compiled files
34
- `-t, --transforms <transforms>` - Comma-separated list of transforms to run
35

36
**Source and Project Options:**
37
- `<srcDir>` - Source directory to transform (required unless using -p)
38
- `-p, --project <dir>` - Compile TypeScript project using tsconfig.json in directory
39

40
**Output Options:**
41
- `--out-extension <extension>` - File extension for output files (default: "js")
42
- `-q, --quiet` - Don't print the names of converted files
43

44
**Transform Configuration:**
45
- `--disable-es-transforms` - Opt out of all ES syntax transforms
46
- `--jsx-runtime <string>` - JSX transformation mode ("classic", "automatic", "preserve")
47
- `--production` - Enable production mode (affects JSX output)
48
- `--jsx-import-source <string>` - Import path prefix for automatic JSX runtime
49
- `--jsx-pragma <string>` - Element creation function for classic JSX runtime
50
- `--jsx-fragment-pragma <string>` - Fragment component for classic JSX runtime
51

52
**Import/Export Options:**
53
- `--keep-unused-imports` - Disable automatic removal of type-only imports/exports
54
- `--preserve-dynamic-import` - Don't transpile dynamic import() to require()
55
- `--inject-create-require-for-import-require` - Use createRequire for TS import = require in ESM
56

57
**Module Interop Options:**
58
- `--enable-legacy-typescript-module-interop` - Use default TypeScript ESM/CJS interop
59
- `--enable-legacy-babel5-module-interop` - Use Babel 5 ESM/CJS interop strategy
60

61
**Directory Options:**
62
- `--exclude-dirs <paths>` - Comma-separated list of directory names to skip
63

64
### CLI Examples
65

66
**TypeScript Project Compilation:**
67
```bash
68
# Using tsconfig.json
69
sucrase -p ./
70
sucrase -p ./packages/core
71

72
# Manual configuration
73
sucrase -t typescript -d dist src --out-extension js
74
```
75

76
**React Development Build:**
77
```bash
78
# Modern React with automatic JSX runtime
79
sucrase -t typescript,jsx \
80
  --jsx-runtime automatic \
81
  --jsx-import-source react \
82
  -d build src
83

84
# Classic React
85
sucrase -t typescript,jsx \
86
  --jsx-runtime classic \
87
  --jsx-pragma React.createElement \
88
  --jsx-fragment-pragma React.Fragment \
89
  -d build src
90
```
91

92
**Node.js CommonJS Build:**
93
```bash
94
# Convert ES modules to CommonJS
95
sucrase -t typescript,imports -d dist src
96

97
# Legacy module interop
98
sucrase -t typescript,imports \
99
  --enable-legacy-typescript-module-interop \
100
  -d dist src
101
```
102

103
**Production Build:**
104
```bash
105
# Optimized production build
106
sucrase -t typescript,jsx,imports \
107
  --production \
108
  --jsx-runtime automatic \
109
  --disable-es-transforms \
110
  -d dist src
111
```
112

113
**Flow Project:**
114
```bash
115
# Flow with JSX
116
sucrase -t flow,jsx,imports -d dist src
117
```
118

119
**Exclude Directories:**
120
```bash
121
# Skip test and spec directories
122
sucrase -t typescript -d dist src \
123
  --exclude-dirs __tests__,spec,stories
124
```
125

126
### Node.js Wrapper Tool
127

128
The `sucrase-node` command provides a simple wrapper around Node.js that automatically registers Sucrase transforms.
129

130
```bash
131
sucrase-node <script>
132
```
133

134
**Usage Examples:**
135

136
```bash
137
# Run TypeScript files directly
138
sucrase-node app.ts
139
sucrase-node server.tsx
140

141
# Equivalent to:
142
node -r sucrase/register app.ts
143
```
144

145
**Features:**
146
- Automatically registers all file types (.js, .jsx, .ts, .tsx)
147
- Uses default transform settings optimized for Node.js
148
- Simpler than manual require hook registration
149
- Ideal for development and quick testing
150

151
### Build Integration Examples
152

153
**Package.json Scripts:**
154
```json
155
{
156
  "scripts": {
157
    "build": "sucrase -t typescript,jsx -d dist src",
158
    "build:prod": "sucrase -t typescript,jsx,imports --production -d dist src",
159
    "dev": "sucrase-node src/server.ts",
160
    "test": "sucrase-node test/runner.ts"
161
  }
162
}
163
```
164

165
**Docker Build:**
166
```dockerfile
167
# Dockerfile
168
FROM node:18
169
WORKDIR /app
170
COPY package*.json ./
171
RUN npm install
172
COPY . .
173
RUN npx sucrase -t typescript,jsx,imports --production -d dist src
174
CMD ["node", "dist/server.js"]
175
```
176

177
**GitHub Actions:**
178
```yaml
179
# .github/workflows/build.yml
180
- name: Build with Sucrase
181
  run: |
182
    npm install
183
    npx sucrase -t typescript,jsx -d dist src
184
    npm test
185
```
186

187
### Error Handling
188

189
The CLI provides detailed error messages with file paths and line numbers:
190

191
```bash
192
$ sucrase -t typescript -d dist src
193
Error transforming src/app.ts: Unexpected token (3:15)
194
  1 | import { Component } from 'react';
195
  2 | 
196
> 3 | const App: Comp = () => <div>Hello</div>;
197
    |               ^
198
  4 | 
199
  5 | export default App;
200
```
201

202
### Exit Codes
203

204
- `0` - Success
205
- `1` - Configuration error or transformation failure
206

207
### Performance Monitoring
208

209
Use the `--quiet` flag to suppress file names for cleaner output in CI/CD:
210

211
```bash
212
# Quiet mode for automated builds
213
sucrase -t typescript,jsx -d dist src --quiet
214

215
# Verbose mode for debugging
216
sucrase -t typescript,jsx -d dist src
217
```
218

219
### TypeScript Project Mode
220

221
When using `-p, --project`, Sucrase reads and respects many tsconfig.json options:
222

223
```bash
224
# Uses tsconfig.json in current directory
225
sucrase -p .
226

227
# Uses tsconfig.json in specified directory  
228
sucrase -p ./packages/core
229
```
230

231
**Supported tsconfig.json options:**
232
- `compilerOptions.jsx` - JSX mode
233
- `compilerOptions.jsxFactory` - JSX pragma
234
- `compilerOptions.jsxFragmentFactory` - JSX fragment pragma
235
- `compilerOptions.jsxImportSource` - JSX import source
236
- `compilerOptions.esModuleInterop` - Module interop behavior
237
- `compilerOptions.verbatimModuleSyntax` - Preserve imports/exports
238

239
**Note:** When using project mode, you cannot specify transforms, source directory, or certain other options as they are inferred from tsconfig.json.