Command Line Interface

The @vercel/ncc CLI provides a comprehensive command-line interface for compiling Node.js modules into single files. It supports multiple commands for building, running, and managing the build cache.

Capabilities

Build Command

Compiles a Node.js module into a single file with all dependencies bundled.

ncc build <input-file> [options]

Options:

• -o, --out [dir] - Output directory for build (defaults to dist)
• -m, --minify - Minify output
• -C, --no-cache - Skip build cache population
• -s, --source-map - Generate source map
• -a, --asset-builds - Build nested JS assets recursively, useful when code is loaded as an asset (e.g., for workers)
• --no-source-map-register - Skip source-map-register source map support
• -e, --external [mod] - Skip bundling 'mod'. Can be used many times
• -q, --quiet - Disable build summaries / non-error outputs
• -w, --watch - Start a watched build
• -t, --transpile-only - Use transpileOnly option with the ts-loader
• --v8-cache - Emit a build using the v8 compile cache
• --license [file] - Adds a file containing licensing information to the output
• --stats-out [file] - Emit webpack stats as json to the specified output file
• --target [es] - ECMAScript target to use for output (default: es2015)
• -d, --debug - Show debug logs

Examples:

# Basic build
ncc build input.js

# Build with minification and source maps
ncc build input.js -o dist -m -s

# Build with external dependencies
ncc build input.js -e aws-sdk -e sharp

# Watch mode for development
ncc build input.js -w

# TypeScript with custom target
ncc build src/main.ts --target es2020

Run Command

Builds and executes a file with full source maps support for testing and debugging.

ncc run <input-file> [options]

Options:

All build options except --out and --watch are supported. The output is written to a temporary directory and executed immediately.

Examples:

# Run a JavaScript file
ncc run app.js

# Run a TypeScript file with debugging
ncc run src/main.ts -d

# Run with external dependencies
ncc run server.js -e express

Cache Command

Manages the ncc build cache for faster subsequent builds.

ncc cache <subcommand>

Subcommands:
  clean    # Clear the build cache
  dir      # Show cache directory path
  size     # Show cache size in MB

Examples:

# Clear the build cache
ncc cache clean

# Show cache directory
ncc cache dir

# Check cache size
ncc cache size

Help Command

Shows usage information and available commands.

ncc help

Version Command

Shows the ncc version.

ncc version

File Extension Handling

ncc automatically detects the appropriate output format based on the input file and package.json configuration:

• .cjs files produce CommonJS output with .cjs extension
• .mjs files or .js files in "type": "module" packages produce ES module output with .mjs extension
• All other .js files produce CommonJS output with .js extension
• TypeScript files (.ts, .tsx) are compiled according to the above rules

TypeScript Support

ncc has built-in TypeScript support with zero configuration required:

• Automatically detects and compiles .ts and .tsx files
• Respects tsconfig.json if present in the project
• Supports TypeScript path mapping and module resolution
• Uses TypeScript version from devDependencies if available

Output Structure

The build command generates:

• index.js (or .cjs/.mjs) - The main compiled output
• index.js.map - Source map (if --source-map enabled)
• sourcemap-register.js - Source map support (if source maps enabled)
• Additional asset files (if the source code references external assets)

Watch Mode

When using --watch, ncc monitors the input file and its dependencies for changes:

• Automatically rebuilds when files change
• Displays "Watching for changes..." message
• Shows build progress and file sizes
• Press Ctrl+C to stop watching

Error Handling

The CLI provides clear error messages for common issues:

• Missing input files
• TypeScript compilation errors
• Webpack bundling errors
• Invalid command-line options
• File system permissions issues

Exit codes:

• 0 - Success
• 1 - General error
• 2 - Invalid usage or command-line arguments