nubjs/nub v0.9.1

Nub 0.9.1

on GitHub

Nub now 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.

Runtime

Threadpool sized to the machine

Node hands async fs, dns.lookup, async zlib and crypto calls, and native addons such as bcrypt and sharp, to a pool of four threads whatever the core count. Nub now sets the size when it starts Node, on every launcher: the file run, nub run, nubx, nub watch and lifecycle scripts.

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 preload removes Nub's own value from process.env once the pool exists, so a cluster worker or child_process spawn gets Node's default; a child that runs through nub is sized again. On Linux the threads beyond four are reniced to 10 after the pool is built, and on the compat tier (Node 18.19–22.14) a --require sidecar builds the pool so the demoted set is exact. A bcrypt route on a 16-vCPU box went from 18 to 66 requests per second under autocannon at 64 connections, mean of three rounds (benchmark); routes that use the pool lightly are within noise of plain Node. The Threadpool page documents the behavior. (#919)

A prefix command in nub.jsonc

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
}

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 chain, then PATH; a path form anchors to the file that set it. A nested nub run, or a wrapper written in Node, does not wrap the same project again. The nubx, nub dlx and node shim entrypoints do not take it, and compat mode runs without it. The field is in the config reference and the JSON schema. (#915)

AsyncContextFrame on Node 22.9–23.x

Nub passes --experimental-async-context-frame on Node 22.9 through 23.x, the band where the flag exists and does not throw. Node 24 made that AsyncLocalStorage implementation the default; on the 22 line it roughly halves the cost of carrying a store across await, which tracing SDKs and request-context plugins pay on every request. (#912)

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: Node 22.23.2 in a 512 MiB–1 GiB budget and Node 24.20.0 at 512 MiB. The flag is hidden from process.execArgv, Workers keep their own resourceLimits, and 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. (#917)

User loader hooks layered above Nub's

Running tsx script.ts under nub run, or a prepare script that does, failed with require is not defined in ES module scope. Nub's load results now carry responseURL, both tiers step aside when an outer resolve hook labels a .ts file with a bare commonjs/module format, and a require.extensions handler that is already registered stays in charge of its extension. (#920)

Package manager

npm installs on Nub's engine

One opt-in routes the two npm verbs an install pipeline runs through Nub's engine:

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 from the same lockfile. Everything else reaches the real npm as typed, including an install that names a package or carries a flag Nub does not translate. Lifecycle scripts run as npm runs them, with NODE_ENV=production when dev dependencies are omitted and ignore-scripts honored from .npmrc and the environment. The engine also runs a file: directory dependency's lifecycle scripts in the link target on an npm-lockfile install, as npm does. The --no-route-installs flag turns the routing off. (#925, docs)

npm lockfile compatibility

Frozen-installing popular npm projects under Nub found refusals of lockfiles npm itself wrote.

Installs and lifecycle scripts

CLI and documentation

• The nub agent docs command prints usage and the table of contents instead of the overview page; --list prints the contents alone and --page selects a page (#930).
• A docs page for the @nubjs/extensions database, with ready-to-use configuration for pnpm and Yarn (5297d2f).
• The blog post De-phantoming the npm ecosystem, a daily scan of 10,000 high-download packages published as that database (#926, 7319aa6, d077198, 8375a03, 11a435e, f231db0, b0a711b, afa009f).
• A Threadpool runtime page, an AsyncLocalStorage entry on the modern APIs page, and a memory-constrained launches section on the runtime overview (#919, #912, #917).
• The config reference shows an absolute nodeExecutable path, with the Windows spelling (5da9a60).
• The GitHub Action page shows setup-nub beside a kept actions/setup-node step (12c2854).
• The Nub 0.9 release post (56175e8), and a blog post's right-gutter table of contents now shows from the lg breakpoint (0ede70a).

Testing & internals

• An npm-incumbent corpus: 28 popular npm projects frozen-installed under Nub in CI and checked against their own lockfile, which is where the #918 and #923 findings came from (#922, ac4fa4f).
• The cross-runtime scoring leaves a test the reference Node itself skips out of the node-relative denominator, for every runtime; the official build skips all 245 quic/ tests. The homepage and README figures are regenerated: Nub passes 98.4% of the 4,690 tests Node 26.7 runs and passes (#931).
• A Windows dispatch benchmark times a nub call from cmd.exe through npm's nub.cmd shim against the hardlinked nub.exe, with its first saved run (e5fa958, 1b8e7ef).
• A runtime benchmark family under tests/bench/runtime/: threadpool, AsyncContextFrame, pool-bound routes (bcrypt, scrypt, pbkdf2, sharp, gzip, brotli, RSA keygen) and pool-priority beside busy co-tenants, with saved runs on 8, 16 and 22 vCPU (9134538, 96f7a14, a33bc4c, b058f75, 746c47c, e88ce4f, ab890a2, d4d9e8f, 92c348e, 250372c, d3d8a38, 78a0225).
• A chart generator for the benchmark figures, with its margin and legend rules (c05a354, 056fa95, a71d9e3, 2e18646, 0e10604, 5a8a8b5, 9654c1b).
• The release workflow holds publish-npm open until every one of the ten packages answers a registry read, so the Docker and install jobs no longer race a package the registry has not served yet (3f87d09).
• Pull-request CI is opt-in behind the ci label, and ci-watch requires the CI gate aggregate before a green verdict (5c0b233, 291af85).
• The docs bake key is renamed __NUB_DOCS_KEY so it counts as internal plumbing under the brand-boundary test (#921).
• The governed rustc wrapper keeps stdin, so a build-script feature probe fails on stable as it should (fa34f36).
• The download-stats snapshot folds paginated release pages before parsing (c25bc82, 2b9a448).
• Local Lat search is wired into the agent workflows (fd626cc).
• Cold-start research notes: the entropy change landed in Node as nodejs/node#65796, and --use-system-ca is not free on a populated macOS keychain (88a0167, d3bf766).

What's Changed

• runtime: enable AsyncContextFrame for AsyncLocalStorage on Node 22.9–23.x by @colinhacks in #912
• config: a prefix field that wraps file runs, scripts, and watch by @colinhacks in #915
• build: rename the docs bake key to __NUB_DOCS_KEY by @colinhacks in #921
• pm: accept the npm lockfiles and projects that npm ci accepts by @colinhacks in #918
• runtime: let a user hook layered above nub's keep ownership of its files by @colinhacks in #920
• tests: an npm-incumbent corpus, frozen-installed under nub and checked against its lockfile by @colinhacks in #922
• pm: record the peer each npm lockfile placement resolves to as a graph edge by @colinhacks in #923
• pm: accept a dependency declared in more than one manifest section by @colinhacks in #928
• pm: run npm ci and npm install on nub's engine behind nub pm shim --route-installs by @colinhacks in #925
• pm: accept a bun-style source identity as a patchedDependencies key by @colinhacks in #929
• agent: show concise docs help and table of contents by @colinhacks in #930
• tests: leave the tests the reference node skips out of the node-relative denominator by @colinhacks in #931
• De-phantoming the npm ecosystem by @colinhacks in #926
• runtime: size libuv's threadpool to the cores on augmented runs by @colinhacks in #919
• compile: precompile ESM and reuse published extractions by @colinhacks in #932
• pm: fill node-gyp's header cache from the provisioned Node by @colinhacks in #935
• Tune the main nursery for memory-constrained Node launches by @colinhacks in #917
• phantom: treat host-provided modules as declared by @colinhacks in #939

Full Changelog: v0.9.0...v0.9.1