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

  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