ncc — Compile a Node.js Project into a Single File

Introduction

ncc is a command-line compiler by Vercel that takes a Node.js project with its entire dependency tree and produces a single output file. It is commonly used to bundle GitHub Actions, AWS Lambda functions, and CLI tools so they can be distributed without a node_modules directory. ncc handles TypeScript, dynamic requires, binary addons, and asset files out of the box.

What ncc Does

• Bundles a Node.js entry point and all its dependencies into one file
• Compiles TypeScript sources without a separate tsc step
• Detects and copies binary native addons and non-JS assets into the output directory
• Resolves dynamic require() calls through static analysis
• Produces source maps for debugging the bundled output

Architecture Overview

ncc is built on top of Webpack with a Node.js-targeted configuration. It traces the dependency graph starting from the entry file, inlines all JavaScript modules, and emits a single CommonJS bundle. Native .node addons and non-JS assets that cannot be inlined are copied to the output directory alongside the bundle. TypeScript support comes from the built-in ts-loader integration. The resulting output runs on any Node.js version without needing npm install.

Self-Hosting & Configuration

• Install globally with npm i -g @vercel/ncc or use npx for one-off builds
• Point ncc at your entry file: ncc build src/index.ts
• Use -o dist to specify the output directory
• Add --minify to reduce bundle size for production
• Use --source-map to emit a source map for stack trace mapping

Key Features

• Zero configuration required for most projects
• Handles TypeScript natively without tsconfig changes
• Supports native Node.js addons and copies them into the output
• Produces reproducible single-file builds for CI and deployment
• Used internally by Vercel for building GitHub Actions and serverless functions

Comparison with Similar Tools

• esbuild — general-purpose bundler; ncc focuses specifically on Node.js server-side bundling
• Webpack — ncc uses Webpack internally but hides all configuration
• pkg — compiles Node.js to a standalone executable with embedded runtime; ncc produces a JS file
• tsup — library bundler using esbuild; ncc targets application bundling with native addon support
• bun build — Bun-specific bundler; ncc works with any Node.js runtime

FAQ

Q: Does ncc work with ESM-only packages? A: ncc outputs CommonJS. It can consume some ESM packages but may struggle with pure ESM that uses top-level await.

Q: Can I use ncc for library packaging? A: ncc is designed for application bundling. For libraries, tools like tsup or unbuild that preserve module formats are a better fit.

Q: How do I handle environment-specific native addons? A: ncc copies .node files to the output directory. You need to build on the same platform where the bundle will run.

Q: Is the output file tree-shaken? A: ncc relies on Webpack tree shaking, which works for ES module syntax. CommonJS require calls are harder to optimize.

Sources

• https://github.com/vercel/ncc
• https://www.npmjs.com/package/@vercel/ncc