Nub: The All-in-One Node.js Power-Up

Nub is a high-performance toolkit designed to augment the standard Node.js environment rather than replace it. Written in Rust, it delivers a developer experience (DX) reminiscent of Bun while remaining fully compatible with stock Node.

🚀 Quick Start Checklist

• Install Nub via shell or npm
• Run a TypeScript file without a build step
• Try the accelerated package installer
• Set up the GitHub Action for CI/CD

---

🛠️ The Nub Ecosystem

Nub consolidates multiple fragmented tools into a single binary. Here is how it maps to the tools you likely already use:

Command Reference

Nub Command	Purpose	Performance Gain
nub index.ts	TS-first execution	$\approx 2.9\times$ faster startup than tsx
nub run dev	Execute scripts	$24\times$ faster than pnpm run
nubx prisma generate	Execute binaries	$19\times$ faster than npx
nub install	Install dependencies	$2.5\times$ faster than pnpm install
nub watch src/server.ts	Native watch mode	Integrated dependency tracking
nub pm shim	Corepack-style shims	Built-in
nub node install 26	Manage Node versions	Integrated version manager
nub upgrade	Update Nub itself	Self-updating binary

---

📥 Installation

Local Setup

Depending on your operating system, use the following commands:

macOS / Linux

curl -fsSL https://nubjs.com/install.sh | bash

Windows (PowerShell)

irm https://nubjs.com/install.ps1 | iex

Via NPM (or pnpm/yarn)

npm install -g --ignore-scripts=false @nubjs/nub

CI/CD Integration

For GitHub Actions, swap actions/setup-node for the Nub equivalent:

uses: actions/setup-node@v4 $\rightarrow$ uses: nubjs/setup-nub@v0

---

🏃 The File Runner (nub file)

Nub allows you to execute files across a wide array of extensions: .js, .ts, .mjs, .cjs, .mts, .cts, .jsx, and .tsx. It is designed to be a drop-in replacement for node, maintaining flag-for-flag and variable-for-variable compatibility via passthrough.

Enhanced Capabilities

Nub adds several "superpowers" to the standard Node.js runtime:

• TypeScript Mastery: Full support for enum and namespace.
• Smart Resolution: Handles extensionless imports and respects tsconfig.json#paths.
• Modern Frontend Tech: Native support for JSX/TSX and Decorators (including emitDecoratorMetadata).
• Cutting Edge Syntax: Supports the using keyword (downleveled via transpiler if necessary).
• Environment Management: Automatic .env* loading, matching the behavior of Vite or Next.js.
• Data Loaders: Built-in support for .yaml, .toml, .jsonc, .json5, and .txt.
• Polyfills & Unflagging:
  • Provides polyfills for Temporal, Worker, and URLPattern.
  • Automatically enables experimental features like node:sqlite, vm.Module, localStorage, WebSocket, and EventSource.

---

⚙️ Under the Hood

Nub leverages modern Node.js extension surfaces that were unavailable during the inception of Deno or Bun.

1. Transpilation: It uses --import or --require to preload module.registerHooks().
2. Native Speed: It embeds oxc (via N-API native addons) for lightning-fast pre-transpilation.
3. Node Provisioning: Nub automatically detects and installs the required Node.js version based on the following precedence:
   1. NODE_EXECUTABLE (Manual override)
   2. package.json#devEngines
   3. .node-version
   4. .nvmrc
   5. package.json#engines

Example Workflow:

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

API Compatibility Matrix

API	Polyfilled (Below Version)	Native (Above Version)
Temporal	$\text{Node} < 26$	$\text{Node} \ge 26$
URLPattern	$\text{Node} < 24$	$\text{Node} \ge 24$
RegExp.escape	$\text{Node} < 24$	$\text{Node} \ge 24$
Error.isError	$\text{Node} < 24$	$\text{Node} \ge 24$
Promise.try	$\text{Node} < 24$	$\text{Node} \ge 24$
Float16Array	$\text{Node} < 24$	$\text{Node} \ge 24$
navigator.locks	$\text{Node} < 24.5$	$\text{Node} \ge 24.5$
vm.Module	Unflagged	Native
ShadowRealm	Unflagged	Native
WebSocket	Unflagged $\text{Node } 20.10$	Native $\text{Node } 22$
EventSource	Unflagged $\text{Node } 20.18$	Native
node:sqlite	Unflagged $\text{Node } 22.5$	Native $\text{Node } 22.13$

---

👁️ Watch Mode

Nub's watch mode is more intelligent than simple glob-based watching. It tracks the resolved dependency graph to determine exactly when a restart is necessary.

• Automatic Tracking: It knows which files are imported and only restarts when those (or their dependencies) change.
• Off-Graph Invalidation: It also monitors critical configuration files that aren't explicitly imported, such as:
  • .env* files
  • The tsconfig.json extension chain
  • package.json
• Engine: It utilizes Node's own --watch mechanism for efficiency.

Usage:

nub watch src/server.ts
# OR
nub --watch src/server.ts