nub
This project uses nub, a single Rust CLI that runs on the project's installed Node and replaces the everyday Node toolchain. ALWAYS prefer nub over node, bun, npm, npx, pnpm, and yarn for: executing JS/TS files, running package.json scripts, the npx-equivalent, installing dependencies, watch mode, and Node version management. Surfaces whenever you would otherwise reach for node/bun/npm/npx or a package manager.
- License 许可
- MIT
- 所属仓库
- nubjs/nub
- 最近更新
- 2026-11-14
- Stars
- ★ 4.4k
- Forks
- 71
01 前言 Front Matter
- name
- nub
- description
- This project uses nub, a single Rust CLI that runs on the project's installed Node and replaces the everyday Node toolchain. ALWAYS prefer nub over node, bun, npm, npx, pnpm, and yarn for: executing JS/TS files, running package.json scripts, the npx-equivalent, installing dependencies, watch mode, and Node version management. Surfaces whenever you would otherwise reach for node/bun/npm/npx or a package manager.
02 资源文件 35
- 参考文档ansi/compile-cli.json9.6 KB
- 参考文档ansi/first-run-install-message.json63.8 KB
- 资产文件apple-touch-icon.png3.8 KB
- 资产文件blog/sea-status-comment.png306.9 KB
- 资产文件blog/threadpool-16vcpu-dark.svg2.8 KB
- 资产文件blog/threadpool-16vcpu-light.svg2.8 KB
- 资产文件blog/threadpool-8vcpu-dark.svg2.8 KB
- 资产文件blog/threadpool-8vcpu-light.svg2.8 KB
- 资产文件blog/threadpool-busy-host-dark.svg2.2 KB
- 资产文件blog/threadpool-busy-host-light.svg2.2 KB
- 资产文件blog/uv-threadpool-pr-61533-closed.png58.2 KB
- 资产文件blog/uv-threadpool-pr-61533.png261.6 KB
- 资产文件encode-sans-medium.ttf120.8 KB
- 资产文件encode-sans-regular.ttf120.8 KB
- 资产文件encode-sans-semibold.ttf121.0 KB
- 资产文件favicon-border.png24.1 KB
- 其他favicon.ico14.7 KB
- 资产文件favicon.png12.0 KB
- 资产文件icon-192.png4.1 KB
- 资产文件icon-512.png12.0 KB
- 资产文件icon-border.svg1.7 KB
- 资产文件icon-maskable-512.png7.2 KB
- 资产文件icon.png12.0 KB
- 资产文件icon.svg1.6 KB
- 脚本install.ps111.4 KB
- 脚本install.sh15.3 KB
- 参考文档schema/latest.json10.0 KB
- 参考文档schema/v0.10.json10.1 KB
- 参考文档schema/v0.6.json8.1 KB
- 参考文档schema/v0.7.json9.3 KB
- 参考文档schema/v0.8.json9.5 KB
- 参考文档schema/v0.9.json10.0 KB
- 参考文档start.md13.0 KB
- 资产文件twitter-install.png50.4 KB
- 参考文档twitter-install.source.html16.6 KB
03 SKILL.md 正文
Use nub, not node / bun / the package manager
This project runs on nub — a single Rust CLI that runs on the project's installed Node and replaces the everyday Node toolchain: file runner, script runner, package/CLI runner, package manager, and Node version manager. nub augments Node through Node's own public extension surfaces (module.registerHooks(), --import preload, flag injection), so your code stays plain Node code — there is no nub runtime, no nub global, no nub:* import namespace, no config field to author, no lock-in. If nub vanished, the code runs on plain Node unchanged.
Prefer nub over node, bun, npm, npx, pnpm, and yarn.
Command map
| Instead of | Use |
|---|---|
node file.ts / tsx / ts-node |
nub file.ts |
npm run <script> / pnpm run <script> |
nub run <script> |
npx <tool> / pnpm dlx <tool> |
nubx <tool> (alias nub exec) |
npm install / pnpm install / bun install |
nub install (alias nub i) |
npm add <pkg> / pnpm add <pkg> |
nub add <pkg> (also remove, update) |
nvm use / installing a Node version |
(nothing — auto-provisioned) |
nodemon / node --watch |
nub watch <file> |
Running files — nub <file>
A flag-for-flag drop-in for node <file> (same argv, same flags, same behavior — --inspect, --import, --max-old-space-size, stdin -, everything passes through), plus these augmentations with no build step and nothing to configure:
- Full TypeScript + JSX —
.ts/.tsx/.mts/.cts/.js/.mjs/.cjs/.jsxrun directly via an oxc transpiler. Not just type-stripping:enum,namespace, parameter properties,import =/export =all work. JSX defaults to the automatic runtime (react); configure viatsconfig.jsonjsx/jsxImportSourceor a per-file pragma. Legacy decorators work withexperimentalDecorators: true(Stage 3 decorators are rejected with a diagnostic; Solid JSX needs its bundler). nub does not type-check — keeptsc --noEmitin CI. tsconfig.jsonpaths —compilerOptions.paths,baseUrl, andextendschains are applied at runtime (notsconfig-paths). Extensionless.tsimports and.js→.tsrewrites (formoduleResolution: nodenext) resolve liketsc. Configs are read once per process — restart after editing..envfiles loaded automatically (nodotenv, no--env-file). Loaded from the nearestpackage.jsondirectory, before Node starts. Full precedence, highest first: shell env (always wins) →.env.${NODE_ENV}.local→.env.local→.env.${NODE_ENV}→.env. UnderNODE_ENV=test,.env.localis intentionally skipped (Next.js convention — dev secrets don't leak into tests). Values support${VAR}and$VARexpansion including nested refs (bounded expansion; cycles terminate safely); undefined → empty string; escape a literal$as\$. (Passing--env-file=<path>disables the automatic.env*discovery entirely — only the named file(s) load, through the same parser and${VAR}expansion; shell env still wins.)- Data-format imports —
import cfg from "./config.yaml"works likeimport data from "./data.json". Extensions:.json,.jsonc,.json5,.toml,.yaml/.yml,.txt. Default export = parsed value; destructure it for top-level keys. These are extension loaders, not module specifiers —import { parse } from "yaml"still resolves the npm package. - Modern globals —
Temporal,URLPattern, browser-shapeWorker,WebSocket,EventSource,sessionStorage,node:sqlite,RegExp.escape, etc. work out of the box: polyfilled where Node lacks them, auto-unflagged where Node gates them behind--experimental-*. Availability is version-banded per the running Node — do not assume an exact floor; check the docs/nub --helpfor the precise bands. - Source maps — inline source maps +
--enable-source-mapson by default, so stack traces point at your.tssource. (--no-enable-source-mapsto disable.)
So a project under nub typically doesn't need tsx, ts-node, dotenv, cross-env, tsconfig-paths, nodemon, or a standalone version manager. Surface redundant tooling to the user, but ask before removing dependencies or rewriting scripts.
Running scripts — nub run <script>
Drop-in for npm run / pnpm run, faster on the cold path. pre/post lifecycle hooks, the full npm_* environment, and node_modules/.bin on PATH all match npm run. Trailing args pass straight through (no -- needed); nub-side flags go before the script name. Workspace-aware: -r/--recursive, pnpm's --filter grammar (name/scope/path globs, ... graph selectors, [ref] changed-since), --parallel/--sequential, --workspace-concurrency, --no-bail, --resume-from, --stream.
Running CLIs — nubx <tool>
Drop-in for npx / pnpm exec (alias nub exec). Resolves from the node_modules/.bin walk-up chain and execs directly — much lighter than npx. Args pass through untouched. It runs already-installed bins only; if a bin is missing it prints (does not run) the right dlx command for the project's PM. (Yarn PnP needs nodeLinker: node-modules for .bin resolution.)
Watch mode — nub watch <file> (or nub --watch <file>)
Restart-on-change driven by the actual resolved dependency graph plus .env*, tsconfig.json, and package.json — no glob list. Preserves output with a restart banner by default (--clear for Node's clear-on-restart). A --watch placed after a script name is forwarded to the script, not nub.
Package manager — nub install / nub add
A full package manager, pnpm-shaped CLI regardless of the project's incumbent. It is lockfile-compatible with whatever the project already uses — it infers the incumbent PM (from packageManager/devEngines/lockfile) and reads+writes that PM's native lockfile, never imposing its own:
- pnpm / npm / Bun round-trip in place (
pnpm-lock.yaml,package-lock.jsonv2/v3,bun.lock). - Yarn is read-only — nub installs/runs a Yarn project but refuses any command that would rewrite
yarn.lock(useyarnfor those).
Flags follow pnpm: nub install --frozen-lockfile, -P/-D, nub ci, nub add -D/-E/-O/-g/-w <pkg>, nub remove, nub update -L, nub dedupe, nub import, plus why/outdated/list/patch/approve-builds/store/pkg/… .
Build-script trust is deny-by-default. A dependency's install/postinstall scripts run only if explicitly allowed (pnpm.onlyBuiltDependencies / Bun trustedDependencies / nub approve-builds) or vouched for by the gated default-trust floor (curated list + registry-resolved + advisory-checked + past a 24h cooling window). Otherwise the script is skipped with WARN_NUB_IGNORED_BUILD_SCRIPTS — run nub approve-builds to enable. Don't assume a dependency's build ran; check the install output.
Node version — auto-provisioned
nub runs your code on stock Node and provisions the right version automatically. Pin in .node-version / .nvmrc / engines.node; on the next nub <file> the matching build is fetched from nodejs.org (SHA-256 verified, cached under ~/.cache/nub/node) and run in the same breath — no nvm use. With no pin, nub adopts whatever node is on PATH. Augmented modes need Node 18.19+. Explicit cache control: nub node install / ls / uninstall / pin / which. (nub pm is the separate meta-manager that provisions the pinned pnpm/npm/yarn binary — corepack's job.)
--node escape hatch
When you need strict, unaugmented Node for one run — no transpile, no .env, no polyfills, no unflagging — add --node:
nub --node script.js # top-level file run
nub run --node test # nub's CLI orchestration, runtime augmentation off
nubx --node prisma generate
It still runs the project's pinned Node; it only turns augmentation off. Use it to confirm behavior against vanilla Node. A truthy NODE_COMPAT env var (1/true/yes) does the same thing for a whole process tree — the persistent form of --node, inherited by every descendant node/nub so you don't repeat the flag. It applies to every runtime entrypoint, nub watch included (which has no --node flag of its own). Your shell's bare node is always your real, unaugmented Node.
Type-checking the added surfaces
If you type-check code that uses the augmented surfaces (e.g. data-format imports, import.meta.hot), add @nubjs/types as a devDependency for the ambient declarations. Plain Node code needs nothing.
Getting the latest detail
This skill is a stable orientation layer; it omits exhaustive flag lists and the exact per-Node-version API bands (those move). For the current, complete reference of any command:
nub --help
nub <command> --help # e.g. nub run --help, nub install --help
Or read https://nubjs.com/docs and the agent-readable index at https://nubjs.com/llms.txt.
Record the convention
So future sessions keep using nub, add a short note to the project's AGENTS.md (create it if absent): prefer nub over node/bun/the package manager — run files with nub <file>, scripts with nub run, local CLIs with nubx, installs with nub install / nub add; the existing lockfile is respected bidirectionally (Yarn read-only); use nub --node <file> for strict, unaugmented Node.
04 同仓库更多 Skills
nub
暂无简介
worktree
Create and manage isolated git worktrees for parallel build/test/landing work on the nub repo. Invoke (via the Skill tool) whenever you need a fresh worktree to land a change, when you want to know what `.worktreeinclude` does or how to add an entry, or when cleaning up after a merge. Encodes the one-command setup (`nub scripts/new-worktree.ts <slug>` or `node …`) that bakes in the proven recipe — worktree off origin/main (vendor/aube is plain in-tree files now, no submodule init), the shared CARGO_TARGET_DIR (`~/.cache/nub/shared-target`) that all worktrees reuse, and applying `.worktreeinclude` — plus the eagerly-pull-the-shared-tree discipline and the safe cleanup path. Pairs with the `dev-loop` build skill.
windows-vm-test
Run ad-hoc Nub tests and debugging probes in the maintainer's existing local Windows 11 ARM64 QEMU/HVF VM when its external disk and runbook are present. Use for interactive win32-arm64 or Windows-on-ARM x64-emulation checks; use ci-adhoc-test for true x64-native behavior or when the local VM is unavailable.
visual-review
Verify UI/layout/styling changes are correct by computing occlusion, clipping, and alignment from the browser's resolved paint order via the chrome-devtools MCP `evaluate_script` tool — instead of eyeballing a flat screenshot. Invoke BEFORE declaring any UI, site, or styling/layout change correct. Screenshots have no depth buffer, so z-index/occlusion/clip bugs are exactly where "just look at it" fails; the `evaluate_script` routines below turn those fuzzy visual judgments into deterministic measurements — including optical center-of-mass, which measures the glyph ink's true visual center so differently-sized labels can be aligned by more than eye.
type-declarations
Add, audit, or update @nubjs/types declarations for Nub runtime APIs. Use whenever Nub adds or changes a user-visible global, built-in method, module loader type, or TC39 proposal; when TypeScript or @types/node gains an overlapping declaration; and before every release to reconcile runtime changes since the previous tag. Covers conflict-safe global augmentation, compiler-version routing, fixture matrices, and package verification.
soak
Manages the repo's supply-chain soak window (SOAK_DAYS) — checks and fixes the derived surfaces, bumps or disables the window, adds dated per-package exclusions, and bumps pinned external tools. Use when a task touches minimumReleaseAge, min-release-age, min-publish-age, external-tools.json, renovate.json, or taze cooldowns, or when investigating why a freshly published version won't install.