ncc
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 projec
SKILL.mdskills/ncc/SKILL.md
GitHub@vercel/ncc — Node.js Compiler Collection
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.
Overview
ncc bundles a Node.js application and all of its node_modules into a single output file. This is ideal for:
- Serverless functions — deploy a single file instead of
node_modules - CLI tools — distribute a self-contained executable
- Docker images — reduce image size by eliminating
node_modules
Installation
npm install -g @vercel/ncc
# Or as a dev dependency
npm install --save-dev @vercel/ncc
Basic Usage
# 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
CLI Options
| 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 |
package.json Integration
{
"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"
}
}
TypeScript Support
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.
Externals
Keep specific modules out of the bundle (useful for native modules or optional dependencies):
# Single external
ncc build input.js -e sharp
# Multiple externals
ncc build input.js -e sharp -e canvas
For serverless environments where the runtime provides certain modules, mark them as
external instead of bundling them. AWS Lambda's supported Node.js runtimes (18.x and
later) bundle AWS SDK for JavaScript v3 (@aws-sdk/* scoped packages), not the
legacy aws-sdk v2 package — Node.js 16.x, the last runtime that provided aws-sdk v2,
reached end of support on 2024-06-12. Mark the specific @aws-sdk/client-* packages your
runtime provides as external (e.g. -e @aws-sdk/client-s3); do not rely on a bare
-e aws-sdk unless you are deliberately targeting an EOL runtime.
Static Assets
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.
Common Patterns
Serverless Function Bundling
# Build a minimal serverless handler
ncc build api/handler.ts -o .output/ -m --no-cache
CLI Tool Distribution
{
"bin": "dist/index.js",
"scripts": {
"prepublishOnly": "ncc build src/index.ts -o dist/ -m"
}
}
GitHub Actions
# 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.
Key Points
- Single-file output — all dependencies inlined, no
node_modulesneeded at runtime - TypeScript native — compiles
.tsfiles directly using the project'stsconfig.json - No config file — entirely driven by CLI flags
- Asset handling — non-JS files are automatically copied to the output directory
- Use externals for native modules — binary
.nodemodules often need to be external - Source maps for debugging — use
-sflag to generate.js.mapfiles - Watch mode for dev — use
-wfor fast iteration during development