Nub 0.9.1

Nub 0.9.1 sizes libuv's threadpool to the cores of the machine on every augmented run, takes a prefix command in nub.jsonc, runs npm ci and npm install on its own engine behind an opt-in shim, and accepts more of the npm lockfiles and projects that npm ci accepts.

Nub is an all-in-one toolkit for Node.js written in Rust. The nub command is flag-for-flag compatible with node, while adding full support for TypeScript, JSX, tsconfig.json, .env loading, and modern Web and ECMAScript APIs. It also includes a fast script runner (nub run), package runner (nubx), Node version manager (nub node), and pnpm-compatible package manager.

Threadpool

Node sends async fs, dns.lookup, zlib and crypto calls to a pool of four threads. Native addons such as bcrypt and sharp queue on the same four. The pool is four threads on a laptop and four on a 64-core server, because libuv reads UV_THREADPOOL_SIZE once and only the environment can change it. Nub now sets it when it starts Node.

nub server.ts                        # pool sized to the cores, 16 on a 16-vCPU box
node server.ts                       # pool of 4
UV_THREADPOOL_SIZE=6 nub server.ts   # your value, used as is

The value applies on every launcher: the file run, nub run, nubx, nub watch and lifecycle scripts. On a 16-vCPU box under autocannon at 64 connections, a bcrypt route went from 18 to 66 requests per second, a sharp thumbnail route from 57 to 179, and a pbkdf2 route from 46 to 131 (mean of three rounds, benchmark). Routes that use the pool lightly read within noise of plain Node.

A pool sized to the host takes every core it can see, which is a cost for whatever shares the box. Three things around the size limit that.

• Extra threads run at a lower priority. On Linux, the threads beyond Node's four run at nice 10. On an idle box they run at full speed; under contention they yield most of the CPU. Twelve busy neighbours lose about 1% of their throughput beside the demoted pool, against 7.5% beside a sixteen-thread pool at normal priority.
• Children keep Node's default. Nub removes its own value from process.env once the pool exists, so a cluster worker, a PM2 fork or any child_process spawn starts with four threads. A child that runs through nub is sized again.
• Windows stops at eight. Each pool thread commits its full stack up front there.

The Threadpool page documents the behavior. (#919)

The prefix field

A project can put a command in front of everything Nub runs for it: a file run, a package.json script, and nub watch.

{
  "prefix": "dotenvx run --"   // split like a shell; the array form takes exact arguments
}

nub server.ts        # dotenvx run -- node server.ts
nub run build        # dotenvx run -- sh -c "<the build script>"
nub watch server.ts  # dotenvx run -- node --watch server.ts

A script is wrapped as a whole, so a script that starts no Node process still runs behind the prefix. The program resolves from the project's node_modules/.bin, then PATH, so a wrapper installed as a devDependency works with no global install; a path form, absolute or relative, anchors to the file that set it. A nub run inside a script, or a wrapper written in Node, does not wrap the same project again. The nubx and nub dlx runners do not take it, and --node runs without it. The field is in the config reference. (#915)

npm installs on Nub's engine

The shims run the package manager the project pins. One opt-in changes that for the two npm verbs an install pipeline runs:

nub pm shim --route-installs

With the marker set, a bare npm ci in a project with a package-lock.json runs nub ci, and a bare npm install runs nub install, both on Nub's engine and from the same lockfile. The notice on stderr names the swap:

$ npm ci
npm ci → nub ci (via nub shim)

Everything else reaches the real npm as typed: npm test, npx, npm publish, a global install, an install that names a package, and an install with a flag Nub does not translate. A routed install runs every lifecycle script as npm does, hands them NODE_ENV=production exactly when dev dependencies are omitted, and honors ignore-scripts from .npmrc and the environment. The shim page lists the translated flags. (#925)

npm lockfile compatibility

A corpus of 28 popular npm projects, frozen-installed under Nub in CI and checked against their own lockfile, found refusals of lockfiles npm itself wrote. Each is fixed.

Memory-constrained launches

On Linux x64, a direct Node launch inside a cgroup memory budget starts the main isolate with a 16 MiB V8 semi-space on two measured releases.

The flag is hidden from process.execArgv, and Workers keep their own resourceLimits. The tuning stands down when Node options, preloads, NODE_OPTIONS, PnP, a prefix, or an environment loader own startup. Other releases, larger budgets, budgets below 512 MiB, watch mode and compiled executables keep Node's defaults, because the larger nursery regressed production SSR above the ranges and raised OOM kills below them. The runtime overview has the policy. (#917)

Other changes

The full release notes list every change in this release.

Get started