0
# Command Line Interface
1

2
The @vercel/ncc CLI provides a comprehensive command-line interface for compiling Node.js modules into single files. It supports multiple commands for building, running, and managing the build cache.
3

4
## Capabilities
5

6
### Build Command
7

8
Compiles a Node.js module into a single file with all dependencies bundled.
9

10
```bash { .api }
11
ncc build <input-file> [options]
12
```
13

14
**Options:**
15

16
- `-o, --out [dir]` - Output directory for build (defaults to dist)
17
- `-m, --minify` - Minify output
18
- `-C, --no-cache` - Skip build cache population
19
- `-s, --source-map` - Generate source map
20
- `-a, --asset-builds` - Build nested JS assets recursively, useful when code is loaded as an asset (e.g., for workers)
21
- `--no-source-map-register` - Skip source-map-register source map support
22
- `-e, --external [mod]` - Skip bundling 'mod'. Can be used many times
23
- `-q, --quiet` - Disable build summaries / non-error outputs
24
- `-w, --watch` - Start a watched build
25
- `-t, --transpile-only` - Use transpileOnly option with the ts-loader
26
- `--v8-cache` - Emit a build using the v8 compile cache
27
- `--license [file]` - Adds a file containing licensing information to the output
28
- `--stats-out [file]` - Emit webpack stats as json to the specified output file
29
- `--target [es]` - ECMAScript target to use for output (default: es2015)
30
- `-d, --debug` - Show debug logs
31

32
**Examples:**
33

34
```bash
35
# Basic build
36
ncc build input.js
37

38
# Build with minification and source maps
39
ncc build input.js -o dist -m -s
40

41
# Build with external dependencies
42
ncc build input.js -e aws-sdk -e sharp
43

44
# Watch mode for development
45
ncc build input.js -w
46

47
# TypeScript with custom target
48
ncc build src/main.ts --target es2020
49
```
50

51
### Run Command
52

53
Builds and executes a file with full source maps support for testing and debugging.
54

55
```bash { .api }
56
ncc run <input-file> [options]
57
```
58

59
**Options:**
60

61
All build options except `--out` and `--watch` are supported. The output is written to a temporary directory and executed immediately.
62

63
**Examples:**
64

65
```bash
66
# Run a JavaScript file
67
ncc run app.js
68

69
# Run a TypeScript file with debugging
70
ncc run src/main.ts -d
71

72
# Run with external dependencies
73
ncc run server.js -e express
74
```
75

76
### Cache Command
77

78
Manages the ncc build cache for faster subsequent builds.
79

80
```bash { .api }
81
ncc cache <subcommand>
82

83
Subcommands:
84
  clean    # Clear the build cache
85
  dir      # Show cache directory path
86
  size     # Show cache size in MB
87
```
88

89
**Examples:**
90

91
```bash
92
# Clear the build cache
93
ncc cache clean
94

95
# Show cache directory
96
ncc cache dir
97

98
# Check cache size
99
ncc cache size
100
```
101

102
### Help Command
103

104
Shows usage information and available commands.
105

106
```bash { .api }
107
ncc help
108
```
109

110
### Version Command
111

112
Shows the ncc version.
113

114
```bash { .api }
115
ncc version
116
```
117

118
## File Extension Handling
119

120
ncc automatically detects the appropriate output format based on the input file and package.json configuration:
121

122
- `.cjs` files produce CommonJS output with `.cjs` extension
123
- `.mjs` files or `.js` files in `"type": "module"` packages produce ES module output with `.mjs` extension
124
- All other `.js` files produce CommonJS output with `.js` extension
125
- TypeScript files (`.ts`, `.tsx`) are compiled according to the above rules
126

127
## TypeScript Support
128

129
ncc has built-in TypeScript support with zero configuration required:
130

131
- Automatically detects and compiles `.ts` and `.tsx` files
132
- Respects `tsconfig.json` if present in the project
133
- Supports TypeScript path mapping and module resolution
134
- Uses TypeScript version from `devDependencies` if available
135

136
## Output Structure
137

138
The build command generates:
139

140
- `index.js` (or `.cjs`/`.mjs`) - The main compiled output
141
- `index.js.map` - Source map (if `--source-map` enabled)
142
- `sourcemap-register.js` - Source map support (if source maps enabled)
143
- Additional asset files (if the source code references external assets)
144

145
## Watch Mode
146

147
When using `--watch`, ncc monitors the input file and its dependencies for changes:
148

149
- Automatically rebuilds when files change
150
- Displays "Watching for changes..." message
151
- Shows build progress and file sizes
152
- Press Ctrl+C to stop watching
153

154
## Error Handling
155

156
The CLI provides clear error messages for common issues:
157

158
- Missing input files
159
- TypeScript compilation errors
160
- Webpack bundling errors
161
- Invalid command-line options
162
- File system permissions issues
163

164
Exit codes:
165
- `0` - Success
166
- `1` - General error
167
- `2` - Invalid usage or command-line arguments