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 project into a self-contained file.
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ncc
- metadata
- { "docs": [ "https://github.com/vercel/ncc" ], "priority": 4, "bashPatterns": [ "\\bnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/ncc\\b", "\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/ncc\\b", "\\bbun\\s+(install|i|add)\\s+[^\\n]*@vercel/ncc\\b", "\\byarn\\s+add\\s+[^\\n]*@vercel/ncc\\b", "\\bncc\\s+build\\b" ], "pathPatterns": [], "importPatterns": [ "@vercel/ncc" ] }
- description
- 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 project into a self-contained file.
02 资源文件 1
- 参考文档agents/openai.yaml169 B
03 SKILL.md 正文
@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 aws-sdk
# Multiple externals
ncc build input.js -e aws-sdk -e sharp
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
# 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
- Single-file output — all dependencies inlined, no
node_modulesneeded at runtime - TypeScript native — compiles
.tsfiles directly using the project'stsconfig.json - No config file — entirely driven by CLI flags
- Asset handling — non-JS files are automatically copied to the output directory
- Use externals for native modules — binary
.nodemodules often need to be external - Source maps for debugging — use
-sflag to generate.js.mapfiles - Watch mode for dev — use
-wfor fast iteration during development
Official Resources
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
review-agent
Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.
plugin-creator
Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.