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

> CLI tool by Vercel that bundles a Node.js application and all its dependencies into a single compact file for easy deployment.

## Install

Save as a script file and run:

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

## Quick Use
```bash
npx @vercel/ncc build src/index.ts -o dist
node dist/index.js
```

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

---
Source: https://tokrepo.com/en/workflows/asset-1b569e2e
Author: Script Depot