0
# @vercel/ncc
1

2
@vercel/ncc is a simple CLI tool and Node.js library for compiling Node.js modules into single files with all their dependencies bundled together. It provides zero-configuration bundling for Node.js applications, similar to how gcc works for compiled languages, enabling minimal deployments and faster startup times for serverless environments.
3

4
## Package Information
5

6
- **Package Name**: @vercel/ncc
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install -g @vercel/ncc` (CLI) or `npm install @vercel/ncc` (programmatic)
10

11
## Core Imports
12

13
For programmatic usage:
14

15
```javascript
16
const ncc = require('@vercel/ncc');
17
```
18

19
For CLI usage, install globally and use the `ncc` command directly.
20

21
## Basic Usage
22

23
### CLI Usage
24

25
```bash
26
# Build a Node.js module into a single file
27
ncc build input.js -o dist
28

29
# Run a module with source maps for development
30
ncc run input.js
31

32
# Clean build cache
33
ncc cache clean
34
```
35

36
### Programmatic Usage
37

38
```javascript
39
const ncc = require('@vercel/ncc');
40

41
// Compile a module
42
const { code, map, assets } = await ncc('/path/to/input.js', {
43
  minify: false,
44
  sourceMap: false,
45
  externals: ['some-external-module']
46
});
47

48
// Write the compiled code
49
require('fs').writeFileSync('dist/index.js', code);
50
```
51

52
## Architecture
53

54
@vercel/ncc is built around several key components:
55

56
- **Webpack Integration**: Uses webpack internally for bundling with custom loaders and plugins
57
- **TypeScript Support**: Built-in TypeScript compilation without additional configuration
58
- **Asset Handling**: Automatic asset relocation and bundling for complete standalone builds
59
- **CLI Interface**: Full-featured command-line interface with watch mode and caching
60
- **Programmatic API**: Node.js API for integration into build processes
61
- **Cache System**: Filesystem-based caching for faster subsequent builds
62

63
## Capabilities
64

65
### Command Line Interface
66

67
Full-featured CLI with support for building, running, and cache management. Includes options for minification, source maps, watch mode, and external dependency handling.
68

69
```bash { .api }
70
ncc <command> [options]
71

72
Commands:
73
  build <input-file> [opts]    # Compile input file to output directory
74
  run <input-file> [opts]      # Build and execute file with source maps
75
  cache clean|dir|size         # Cache management operations
76
  help                         # Show usage information
77
  version                      # Show ncc version
78
```
79

80
[Command Line Interface](./cli.md)
81

82
### Programmatic API
83

84
Node.js API for integrating ncc into build processes and tools. Supports all CLI features plus additional programmatic options like custom webpack configurations and asset handling.
85

86
```javascript { .api }
87
const ncc: (entry: string, options?: NccOptions) => Promise<NccResult> | NccWatcher;
88

89
interface NccOptions {
90
  cache?: string | boolean;
91
  externals?: string[] | { [key: string]: string };
92
  minify?: boolean;
93
  sourceMap?: boolean;
94
  assetBuilds?: boolean;
95
  watch?: boolean;
96
  // ... additional options
97
}
98

99
interface NccResult {
100
  code: string;
101
  map?: string;
102
  assets: { [filename: string]: { source: Buffer | string; permissions: number } };
103
  symlinks: { [path: string]: string };
104
  stats: any;
105
}
106
```
107

108
[Programmatic API](./api.md)
109

110
## Core Types
111

112
```javascript { .api }
113
interface NccOptions {
114
  /** Custom cache path or disable caching */
115
  cache?: string | boolean;
116
  /** Custom asset emission function */
117
  customEmit?: (path: string) => boolean | void;
118
  /** Enable ES module output */
119
  esm?: boolean;
120
  /** External modules to exclude from bundling */
121
  externals?: string[] | { [key: string]: string };
122
  /** Output filename (default: 'index.js') */
123
  filename?: string;
124
  /** Enable minification */
125
  minify?: boolean;
126
  /** Generate source maps */
127
  sourceMap?: boolean;
128
  /** Include source-map-support */
129
  sourceMapRegister?: boolean;
130
  /** Source map base prefix */
131
  sourceMapBasePrefix?: string;
132
  /** Build nested JS assets recursively */
133
  assetBuilds?: boolean;
134
  /** Enable watch mode */
135
  watch?: boolean;
136
  /** Enable V8 compile cache */
137
  v8cache?: boolean;
138
  /** Directory filter for assets */
139
  filterAssetBase?: string;
140
  /** List of existing asset names */
141
  existingAssetNames?: string[];
142
  /** Disable build summaries */
143
  quiet?: boolean;
144
  /** Enable debug logging */
145
  debugLog?: boolean;
146
  /** Use TypeScript transpile-only mode */
147
  transpileOnly?: boolean;
148
  /** License file output */
149
  license?: string;
150
  /** ECMAScript target version */
151
  target?: string;
152
  /** Production mode */
153
  production?: boolean;
154
  /** Package.json main fields resolution order */
155
  mainFields?: string[];
156
}
157

158
interface NccResult {
159
  /** Compiled JavaScript code */
160
  code: string;
161
  /** Source map JSON string (if enabled) */
162
  map?: string;
163
  /** Asset files with their content and permissions */
164
  assets: { [filename: string]: { source: Buffer | string; permissions: number } };
165
  /** Symbolic links mapping */
166
  symlinks: { [path: string]: string };
167
  /** Webpack compilation statistics */
168
  stats: any;
169
}
170

171
interface NccWatcher {
172
  /** Set build completion handler */
173
  handler(callback: (result: NccResult & { err?: any }) => void): void;
174
  /** Set rebuild start handler */
175
  rebuild(callback: () => void): void;
176
  /** Close the watcher */
177
  close(): void;
178
}
179
```