Runtime

Run a TypeScript file directly — no tsconfig, no build step, no ts-node:

nub index.ts
nub server.tsx
nub script.js

On top of stock Node, nub <file> adds a modern runtime:

• 🦆 Full TypeScript — non-erasable syntax (enum, namespace, parameter properties), emitDecoratorMetadata decorators
• ⚛️ JSX / TSX — the automatic runtime by default
• 🧭 Editor-style resolution — extensionless imports, .js → .ts rewriting, tsconfig.json#paths
• 🆕 Modern syntax like using — transpiler-downleveled on older Node
• 🔐 Automatic .env* loading — Next.js / Vite parity, with ${VAR} expansion
• 🗂️ Data-file imports — .yaml, .toml, .jsonc, .json5, .txt as parsed default exports
• 🌐 Modern globals backfilled per Node version — Temporal, URLPattern, WebSocket, EventSource, node:sqlite, and more
• 🧵 Source maps in stack traces, automatically
• ⚡ ~2.9× faster startup than tsx

And it's a true drop-in for node: same argv shape, same flag set, same behavior — every flag reaches Node verbatim. No vendor-specific API surface, no lock-in. Pass --node (or set NODE_COMPAT=1) to turn every augmentation off and run on plain Node.

Supported versions and tiers

The hard floor is Node 18.19 — below it no loader-hook API can carry Nub's augmentations, so Nub refuses to run. Above the floor, augmentation is delivered through one of two tiers:

• Fast tier — sync module.registerHooks(), run in-thread via a --require CJS preload. No loader-worker, lower startup overhead.
• Compatibility tier — async module.register(), run in a loader-worker thread via an --import ESM preload. Same augmentations, a little more startup cost.

Nub selects the tier from your Node version. The fast tier needs sync module.registerHooks(), which Node added in v23.5.0 and backported to v22.15.0 — and never backported to the 20.x line. So the tier boundary lands differently per Node major:

A dash in the fast-tier column means that line has no fast-tier build — every patch runs in the compatibility tier. Both tiers are fully supported; nothing about your code changes between them. A ✓ marks the fast-tier versions, recommended for the lowest startup overhead — the latest (Node 26) is the default.

Augmentations

In brief:

• TypeScript — the whole TypeScript surface runs directly, including non-erasable syntax (enum, namespace, parameter properties). Types are stripped, not checked.
• JSX — .jsx and .tsx files run with the modern automatic runtime by default, configured through tsconfig.json or a per-file @jsxImportSource pragma.
• Decorators — legacy decorators run with no build step under experimentalDecorators, including emitDecoratorMetadata for the DI / ORM ecosystem.
• Resolution — extensionless imports, .js → .ts rewriting, and tsconfig.json path aliases resolve at runtime, the way tsc and your editor resolve them.
• Environment variables — .env* files load into the environment before Node starts, with ${VAR} expansion. No dotenv, no --env-file.
• Loaders — import .yaml, .toml, .jsonc, .json5, and .txt files directly as parsed values, with no npm parser.
• Modern APIs — modern globals and built-ins (Temporal, URLPattern, WebSocket, EventSource, node:sqlite, and more) work out of the box, polyfilled or unflagged per Node-version band.
• Workers — the browser-shape Worker global runs your .ts entry points, wrapping node:worker_threads.
• Web Storage — localStorage / sessionStorage behavior and the opt-in that backs persistent storage.

Modern APIs

Modern globals — TC39, web-platform, and newer Node built-ins — work out of the box under Nub. Whatever Node version you run, the API is there — native where Node ships it, and where Node doesn't, Nub fills the gap automatically. You write against the API; the version split is Nub's problem, not yours.

const now = Temporal.Now.plainDateTimeISO();
const route = new URLPattern({ pathname: "/u/:id" });
const ws = new WebSocket("wss://api.example.com");
const stream = new EventSource("https://api/stream");
const { DatabaseSync } = require("node:sqlite");

Two mechanisms do the work, picked per API: Nub either preloads a JS polyfill (feature-detected, so it steps aside the moment the native global appears) or injects the --experimental-* flag that an older Node hides the API behind. Once Node stabilizes an API, it's native and Nub does nothing.

The minimum version column is the lowest Node where the API works under Nub.

A dash means the API works across the full supported range, 18.19 and up. The floored rows have a real cutoff, because the underlying Node mechanism doesn't exist below it:

• The WebSocket global needs Node 20.10 — the flag Nub injects below the native line (Node 22) doesn't exist on older 20.x patches.
• The EventSource global needs Node 20.18, the patch where Node added the flag on the 20 LTS line.
• The node:sqlite module needs Node 22.5, where Node first shipped it.
• Importing a native .node addon from an ES module needs Node 22.20 (or 23.6 on the 23 line), where Node added the flag Nub injects. It is never native — Node keeps the import behind the flag — so Nub injects it on every version that has it.

Node version resolution

Like Corepack's shims, nub itself auto-installs Node versions as needed. When you run a file with nub, it infers the version of Node your project expects and provisions it — downloading and caching the matching stock build if it isn't already on your machine. The inference walks up from the working directory to the nearest pin, taking the first source that yields a version. Highest precedence first:

• NODE_EXECUTABLE — an explicit path to a Node binary (a hard override)
• package.json → devEngines.runtime
• .node-version
• .nvmrc
• package.json → engines.node (a range)
• the node on your PATH, when nothing is pinned

This resolved Node version is auto-installed and cached for future runs.

$ echo 26 > .node-version
$ nub hello.ts
Using Node.js 26.4.0 (resolved from .node-version)
Installed in 9.8s
Hello world!

A few precision details the common case never makes you think about:

• Discovery walks up the directory tree to the nearest pin, and skips pin files that live inside an installed dependency (under node_modules) — a dependency's own CI pin never drives your project.
• The package.json fields (devEngines.runtime, engines.node) are read from the workspace root manifest when one exists above you — a monorepo pins its Node once at the root.
• Once a version is pinned, Nub finds a binary for it in order: the node on PATH (so fnm / Volta / mise auto-switching just works) → Nub's own download store (~/.cache/nub/node/<version>/) → an nvm-installed version → download the matching stock build from nodejs.org, SHA-256 verified and cached.

For pinning, pre-installing, and the nub node subcommands, see Managing Node versions.

A drop-in for node

Anything node <args> accepts, nub <args> accepts too. Pass-through is the default for the entire flag space — every flag reaches Node verbatim:

# diagnostics
--prof  --cpu-prof  --report-*
# module resolution
--conditions  --preserve-symlinks
# inspector
--inspect  --inspect-brk
# warnings
--no-warnings  --trace-deprecation

Reading a program from stdin works the same way node - does.

nub --max-old-space-size=4096 build.ts
nub --import ./instrument.js server.ts
nub script.ts --port 3000 --verbose   # everything after the file is your script's argv
echo 'console.log(1 + 1)' | nub -

Compatibility mode

Nub augments by default. Compatibility mode turns every augmentation off — no load hook, no preload, no unflagging, no .env loading — and runs your code on plain Node, exactly as node <file> would. It still runs the project's pinned Node (version provisioning stays on), so it's the additivity escape hatch and the differential-debugging tool: it makes the "would a plain-Node user get the same result?" test real. (This is distinct from the compatibility tier — the startup path for the Node lines without sync registerHooks, in the table above — which is about how augmentation is delivered, not whether it runs.)

There are two spellings, a per-invocation flag and a tree-wide env var, and they compose — either one forces compatibility mode.

--node

Pass --node to run a single invocation with zero augmentation. Your code runs on the project's pinned Node (from .node-version / .nvmrc, fetched if missing), vanilla — which makes it the tool for differential debugging: does this reproduce on plain Node, on the exact version this project pins? A bare node script.js can't answer that, because it runs your shell's Node, not the project's.

nub --node script.js     # the project's pinned Node, vanilla
node script.js           # your shell's Node, unaugmented, unprovisioned

NODE_COMPAT

Setting a truthy NODE_COMPAT (1, true, or yes, case-insensitive) is the project/tree-wide form of --node. It has the identical effect — zero augmentation, Node-version provisioning still on — but it's persistent and inherited by every descendant node / nub in the tree, so you don't repeat --node per invocation:

export NODE_COMPAT=1     # every nub/node in this shell now runs vanilla
nub script.ts            # plain Node, still on the project's pinned version

How it works

Every augmentation rides on Node's own extension surfaces — Nub patches nothing and ships no runtime of its own. It registers a module.registerHooks() load hook (an async module.register() loader-worker on the compatibility tier) for transpilation and resolution, and injects a small --import preload for the globals and .env loading. On the fast tier, transpilation runs through an embedded oxc N-API addon. The test for any augmentation is whether a user on plain Node, plus the corresponding module.register() / --import / npm addon, would get the same result — which is exactly what --node and NODE_COMPAT turn back off.