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

CLI Options

package.json Integration

TypeScript Support

ncc natively supports TypeScript — no separate tsc step needed:

ncc uses the project's tsconfig.json automatically.

Externals

Keep specific modules out of the bundle (useful for native modules or optional dependencies):

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

CLI Tool Distribution

GitHub Actions

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