perf: reduce build memory and time by ovflowd · Pull Request #1156 · nodejs/doc-kit

ovflowd · 2026-10-07T21:49:45Z

Description

Building the Node.js docs peaks at 3.1–3.8GB of memory, while a single page only needs ~100MB. Node core only builds the HTML docs on machines with more than 5GiB of memory, and silently skips them otherwise. That's what happens on its ubuntu-slim doc CI, whose docs artifact has no HTML at all.

This PR brings the peak down to 1.7–2.4GB, and the build time to less than half:

Shiki registers grammars on demand. Once a thread highlighted code, the Shiki plugin registered all ~250 grammars Shiki bundles, and importing it imported all of them on every thread loading jsx-ast. The docs use about ten languages. Each one is now registered the first time code in it is highlighted, which takes highlighting from ~17s of CPU to ~4s, and the themes go to Shiki by name, so it stops parsing them again for every block. @node-core/rehype-shiki's plugin module still imports every grammar (~33MB and ~0.25s per thread) until nodejs/nodejs.org#9212 is released.
Highlighted code reaches pages as static markup. Every highlighted token became a hast node, then a JSX element, then generated code, only to be rendered back into the same HTML. A plugin after Shiki embeds the code blocks, and types and signatures are embedded as they're highlighted, before rehype-raw would parse each of their tokens again. Each thread also highlights a type only once: of the ~20,000 types the docs highlight, 741 differ.
all.html renders in the worker pool, unminified. It was rendered and minified on the main thread (~1GB), and the minifier's WASM memory grows to ~12× the page without ever shrinking. Unminified, it's 5% larger, or ~2% once gzipped.
Vite runs in a child process. Rolldown only returns its native memory (~250MB here) when its process exits. The new createChildProcess in core runs a module in a process of its own and calls it over birpc (MIT, no dependencies). The Vite adapter runs in one, which ends once the pages are compiled, before they render.
Idle workers end after 500ms instead of a second, so the jsx-ast workers' heaps (~800MB) are gone while the main thread bundles the site, which is when the build peaked.
Worker heaps are limited to 512MB by default (new workerHeapSize option, --worker-heap-size). V8 lets a heap grow to several times its live data before collecting it, four times with the 4GB limit workers get on machines with 16GB+. It costs 3–5% of build time, spent collecting garbage.
Smaller fixes: the generated code and rendered HTML are flattened once complete (strings built with += held ~10× their text), and each thread only imports the modules it uses.

How a build runs

The main thread schedules the generators and holds their results. The work goes to a pool of worker threads, and bundling to a child process of its own, each ending once its part is done:

sequenceDiagram
  participant M as Main thread
  participant W as Worker pool (Piscina)
  participant V as Vite child process

  Note over W: up to 4 workers, 512MB of heap each
  M->>W: ast, metadata and jsx-ast chunks
  W-->>M: each page's code, highlighted code as static markup
  Note over W: workers idle for 500ms end
  M->>V: createChildProcess(vite.mjs)
  M->>V: buildServer, buildClient (birpc)
  V-->>M: component library, client assets
  M->>V: compile each page program
  V-->>M: compiled page modules
  M->>V: close()
  Note over V: exits, and Rolldown's memory with it
  M->>W: page tasks, all.html first
  Note over W: import, render, template, minify, write
  W-->>M: written pages

With threads: 1, the main thread runs the chunks itself.

Note

On Node.js 26, an ended worker's memory stays in the process for the workers started after it rather than going back to the system. Only Node's --no-memory-pool-share-memory-on-teardown gives it back, which code can't set and only Node.js 26 has. The docs mention it as a caveat, but it's probably worth raising upstream with Node.js.

Validation

node --run test (759 tests) passes at every commit, and node --run format:check and node --run lint pass.
Every page matches main, on the web target (71 pages) and on Node core's config (741), except all.html, which is unminified, and three C++ pages (addons, embedding, n-api), whose grammar now comes from core's own shiki (4.4.3) instead of the one @node-core/rehype-shiki pins (4.3.1).
With Node's --max-old-space-size, which limits every isolate, the Node core build passes at 384MB, where main needs 768MB. With --worker-heap-size alone, the workers build every page down to ~350MB.

Benchmarks

main → this branch, building Node core's docs with its config (legacy-json-all + section-pages) unless noted. Medians of 3 interleaved runs on an M4 Pro; peak memory is the physical footprint of every process in the build. They were measured without the grammar import that nodejs/nodejs.org#9212 removes, so they hold once @node-core/rehype-shiki is bumped.

Build	Peak memory	Duration	CPU time
Node 26, 4 threads	3,491MB → 1,743MB (-50%)	22.9s → 9.8s	86.5s → 42.2s
Node 26, 1 thread	3,595MB → 2,377MB (-34%)	52.3s → 22.2s	64.5s → 28.9s
Node 24, 4 threads	3,811MB → 2,241MB (-41%)	25.8s → 10.3s	93.5s → 45.0s
`web` target, Node 26	3,131MB → 1,815MB (-42%)	17.7s → 6.8s	58.5s → 29.2s

With one thread, the main thread does all the work, and workerHeapSize doesn't apply. Node's --max-old-space-size=768 brings that build to 1.63GB in the same time.

Related Issues

Refs: #815
Refs: nodejs/node#62045
Depends on nodejs/nodejs.org#9212 (then a release of @node-core/rehype-shiki to bump here)

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format:check & node --run lint.
I've covered new added functionality with unit tests if necessary.

vercel · 2026-10-07T21:49:53Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
api-docs-tooling	Ready	Preview	Oct 10, 2026 4:32pm UTC

cloudflare-workers-and-pages · 2026-10-07T21:50:42Z

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Success ✅ View logs ↗	No Preview URL. Enable ↗	`679c997`	2026-10-10T16:33:06.552Z	View logs ↗
Build: Success ✅ View logs ↗	No Preview URL. Enable ↗	`6ae35a4`	2026-10-10T16:18:29.109Z	View logs ↗
Build: Success ✅ View logs ↗	No Preview URL. Enable ↗	`b191224`	2026-10-10T15:24:19.601Z	View logs ↗
Build: Failed ❌ View logs ↗		`ca2087e`	2026-10-10T15:19:46.449Z	View logs ↗
Build: Failed ❌ View logs ↗		`6c45a67`	2026-10-10T14:29:53.488Z	View logs ↗
Build: Failed ❌ View logs ↗		`dd8f6c1`	2026-10-10T11:59:51.605Z	View logs ↗
Build: Failed ❌ View logs ↗		`4f2e846`	2026-10-08T17:07:36.252Z	View logs ↗
Build: Failed ❌ View logs ↗		`d41d989`	2026-10-08T15:54:02.554Z	View logs ↗
Build: Failed ❌ View logs ↗		`e66eea8`	2026-10-08T13:09:12.156Z	View logs ↗
Build: Failed ❌ View logs ↗		`e63c654`	2026-10-08T12:16:56.748Z	View logs ↗

View all previews: View all previews ↗

codecov · 2026-10-07T21:50:44Z

Codecov Report

❌ Patch coverage is 99.34162% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.53%. Comparing base (7238bb1) to head (679c997).

Files with missing lines	Patch %	Lines
packages/cli/bin/commands/generate.mjs	0.00%	7 Missing ⚠️
...ages/node-legacy/src/legacy-html/plugins/shiki.mjs	75.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1156      +/-   ##
==========================================
+ Coverage   93.32%   93.53%   +0.21%     
==========================================
  Files         273      282       +9     
  Lines       27050    28057    +1007     
  Branches     2722     2815      +93     
==========================================
+ Hits        25244    26244    +1000     
- Misses       1784     1791       +7     
  Partials       22       22

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-10-07T21:51:26Z