openai/ncc

@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

1. Single-file output — all dependencies inlined, no node_modules needed at runtime
2. TypeScript native — compiles .ts files directly using the project's tsconfig.json
3. No config file — entirely driven by CLI flags
4. Asset handling — non-JS files are automatically copied to the output directory
5. Use externals for native modules — binary .node modules often need to be external
6. Source maps for debugging — use -s flag to generate .js.map files
7. Watch mode for dev — use -w for fast iteration during development

Official Resources

• ncc GitHub
• Vercel Blog — ncc Introduction