@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 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.

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_modules needed at runtime
TypeScript native — compiles .ts files directly using the project's tsconfig.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 .node modules often need to be external
Source maps for debugging — use -s flag to generate .js.map files
Watch mode for dev — use -w for fast iteration during development

ncc