Expert guidance for @vercel/ncc — a simple CLI for compiling Node.js modules into a single file with all dependencies included. Use when bundling serverless functions, CLI tools, or any Node.js project into a self-contained file.
You are an expert in @vercel/ncc, Vercel's simple CLI for compiling a Node.js module into a single file, together with all its dependencies.
ncc bundles a Node.js application and all of its node_modules into a single output file. This is ideal for:
node_modulesnode_modulesnpm install -g @vercel/ncc
# Or as a dev dependency
npm install --save-dev @vercel/ncc
# Compile index.js into dist/index.js
ncc build input.js -o dist/
# Watch mode for development
ncc build input.js -o dist/ -w
# Run directly without writing to disk
ncc run input.js
| Flag | Description |
|---|---|
-o, --out [dir] | Output directory (default: dist) |
-m, --minify | Minify the output |
-s, --source-map | Generate source maps |
-a, --asset-builds | Build nested JS assets recursively |
-e, --external [mod] | Keep module as external (don't bundle) |
-w, --watch | Watch mode — rebuild on changes |
-t, --transpile-only | Skip TypeScript type checking |
--license [file] | Output licenses to a file |
-q, --quiet | Suppress non-error output |
--no-cache | Skip the build cache |
--no-asset-builds | Skip nested JS asset builds |
{
"scripts": {
"build": "ncc build src/index.ts -o dist/ -m",
"build:watch": "ncc build src/index.ts -o dist/ -w",
"start": "node dist/index.js"
},
"devDependencies": {
"@vercel/ncc": "^0.38.0"
}
}
ncc natively supports TypeScript — no separate tsc step needed:
# Compiles TypeScript directly
ncc build src/index.ts -o dist/
# Skip type checking for faster builds
ncc build src/index.ts -o dist/ -t
ncc uses the project's tsconfig.json automatically.
Keep specific modules out of the bundle (useful for native modules or optional dependencies):
# Single external
ncc build input.js -e aws-sdk
# Multiple externals
ncc build input.js -e aws-sdk -e sharp
For serverless environments where the runtime provides certain modules (like AWS Lambda's aws-sdk), mark them as external.
ncc handles non-JS assets (.json, .node, binary files) by copying them to the output directory alongside the compiled JS file. They are referenced correctly at runtime.
# Build a minimal serverless handler
ncc build api/handler.ts -o .output/ -m --no-cache
{
"bin": "dist/index.js",
"scripts": {
"prepublishOnly": "ncc build src/index.ts -o dist/ -m"
}
}
# Bundle a GitHub Action into a single file
ncc build src/index.ts -o dist/ -m --license licenses.txt
GitHub Actions require all dependencies bundled — ncc is the recommended bundler for custom JS/TS actions.
node_modules needed at runtime.ts files directly using the project's tsconfig.json.node modules often need to be external-s flag to generate .js.map files-w for fast iteration during development