Skip to content

perf: let jsx-ast and html start on their dependency's first chunk - #1241

Open
ovflowd wants to merge 7 commits into
mainfrom
perf/stream-html
Open

ovflowd wants to merge 7 commits into
mainfrom
perf/stream-html

Conversation

@ovflowd

@ovflowd ovflowd commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

Description

This PR lets jsx-ast and html start on their dependency's first chunk, so with more than one thread, page building and rendering overlap with the generators before them. It's part of the stack that splits #1205.

  • jsx-ast builds each page as its module's entries arrive. Once its input ends, it emits { manifest }, every page's head in the order the site lists them, without waiting for the pages still being built.
  • html compiles each page as it arrives, bundles the component library and the client assets as soon as the manifest does, and renders the pages as they're compiled.
  • Bundler adapters' compile can now run before and alongside buildServer and buildClient.

jsx-ast now yields pages in the order their entries arrive, plus the { manifest } item, which is a breaking change for anything reading its output.

Site build main This PR
4 threads 9.82s, 1728MB 8.12s (-17%), 2179MB (+26%)
6 threads 8.56s, 2280MB 6.82s (-20%), 2821MB (+24%)

Full Node.js docs, medians of 5 runs. The extra memory is stages that ran one after the other now running at once.

Validation

Added tests for jsx-ast building pages as they arrive and sending the manifest while worker.stream holds back its next batch, and for html bundling once the manifest arrives and building the same site from its whole input. On 12 of Node.js's API docs, the output is byte-identical to main's at 1 and 4 threads.

Related Issues

Refs: #1205

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

vercel Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
api-docs-tooling Ready Ready Preview Nov 20, 2026 9:46pm UTC

Request Review

@codecov

codecov Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 99.73661% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.99%. Comparing base (ad826e4) to head (d39a4ae).

Files with missing lines Patch % Lines
...s/react/src/jsx-ast/utils/__tests__/merge.test.mjs 94.73% 3 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1241      +/-   ##
==========================================
+ Coverage   93.79%   93.99%   +0.20%     
==========================================
  Files         294      298       +4     
  Lines       30476    31477    +1001     
  Branches     3100     3205     +105     
==========================================
+ Hits        28584    29586    +1002     
+ Misses       1870     1869       -1     
  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.

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

🚀 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 ↗ d39a4ae 2026-11-20T21:46:30.925Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 3cf9f57 2026-11-18T03:38:49.430Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 759ea01 2026-11-17T14:45:14.349Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ b3f5826 2026-11-13T16:49:32.564Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 54ee66f 2026-11-11T00:07:37.650Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 3ae80f0 2026-11-10T20:54:08.729Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 03967db 2026-11-09T13:26:27.211Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ f6b39c9 2026-11-09T10:38:16.346Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 67967e0 2026-11-09T11:04:18.304Z View logs ↗
  • Build: Success ✅

View logs ↗
No Preview URL. Enable ↗ 1b6904e 2026-11-09T02:28:44.798Z View logs ↗

View all previews: View all previews ↗

kgeminicdev

This comment was marked as low quality.

ovflowd and others added 6 commits November 17, 2026 22:37
With more than one thread, jsx-ast builds pages as their entries arrive
and html compiles, bundles and renders them as it receives them, so
page building and rendering overlap with the generators before them.
The generated files are unchanged.

jsx-ast yields its pages in the order their entries arrived, and once
every page has, a { manifest } item with all their heads in that order.
html compiles each page as it comes, bundles the component library and
the client assets as soon as the manifest does, and has the workers
render the pages as they are compiled. To list the pages as the site
does, headingSortFn is now exported. Bundler adapters' compile can now
run before and alongside buildServer and buildClient.

createChannel is the queue html hands its compiled pages to the workers
on, and merge yields from several async iterables as items arrive: jsx-ast
announces the manifest next to its pages with it.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Assisted-by: Claude Sonnet 5.5 <noreply@anthropic.com>
worker.stream now reads the next batch once there's room for its
chunks, so jsx-ast's manifest goes out once every page has been read
that way, still without waiting for the pages being built. The
changeset also named @doc-kit/core/utils, which isn't a module:
createChannel and merge come from utils/channel.mjs and
utils/generators.mjs.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
… the channel

jsx-ast's batches hold whole modules, as metadata's and section-pages'
do, so it reads them with toBatches instead of regrouping them. The
replay no longer waits on a signal, so createSignal comes with the
channel, its only caller.

Co-authored-by: Aviv Keller <me@aviv.sh>
Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
worker.stream takes its next batch only once there's room for its
chunks, so jsx-ast's describe() was read no faster than the pool built
pages, and the manifest went out only once the last of section-pages'
batches got room: on Node.js's docs that's with 12 to 18 page chunks
left. html bundles once the manifest arrives and renders nothing until
the bundles are built, so bundling stopped overlapping with building
the pages, and so did rendering, all.html's included.

jsx-ast now describes every page as it arrives into a channel, which
worker.stream reads as it has room. The manifest goes out once the
input ends, as before the backpressure. A failure reading the input
reaches the output through the manifest. The channel holds what the
replay of section-pages' output would hold until read anyway.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
createSignal had the channel as its only caller, so the channel keeps
its own promise to wake its reader, and misc.mjs is as on main. The
channel queues items, not batches: merge pushes single items through
it. jsx-ast's describe pushes into the channel itself, named described
as it holds descriptors, and readPages goes. html's alongside becomes
writeWhileCompiling, which says what it decides.

The test of the manifest not waiting for the pages goes, as the one of
worker.stream holding back the next batch checks the same and more.
html's test of the bundles' timing no longer reads all.html back, which
its sidebar-order test checks, and the channel's tests use
Array.fromAsync.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Since the layer below, a generator that streams its input always gets
an async iterable, so jsx-ast and html drop toBatches and take only
that type. html's tests give it its pages with once, and jsx-ast's test
of its whole input compares two batches with one.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

api-links Generator

Performance estimate (single CI run)

  • Generation time: 7.1% slower (980.00 ms → 1.05 s)
  • Peak memory: 1.0% higher (273.61 MB → 276.26 MB)

json Generator

Performance estimate (single CI run)

  • Generation time: 35.8% slower (6.60 s → 8.96 s)
  • Peak memory: 3.5% lower (922.53 MB → 889.91 MB)

legacy-html Generator

Performance estimate (single CI run)

  • Generation time: 0.6% faster (13.92 s → 13.83 s)
  • Peak memory: 8.0% higher (1.35 GB → 1.46 GB)

legacy-json Generator

Performance estimate (single CI run)

  • Generation time: 11.5% slower (7.28 s → 8.12 s)
  • Peak memory: 4.3% higher (915.02 MB → 954.16 MB)

llms-txt Generator

Performance estimate (single CI run)

  • Generation time: 32.8% slower (5.46 s → 7.25 s)
  • Peak memory: 4.7% higher (851.65 MB → 891.45 MB)

orama-db Generator

Performance estimate (single CI run)

  • Generation time: 4.3% slower (7.36 s → 7.68 s)
  • Peak memory: 0.7% higher (998.16 MB → 1004.91 MB)

web Generator

Performance estimate (single CI run)

  • Generation time: 15.4% slower (18.08 s → 20.87 s)
  • Peak memory: 21.8% higher (1.49 GB → 1.82 GB)

@avivkeller avivkeller left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we can do this without the merging of AsyncIterables (since that, IMO can be confusing 😓)

The only reason jsx-ast needs merge is to slip { manifest } in mid-stream. What if jsx-ast sent the manifest first instead?

const descriptors = [];

for await (const entries of input) {
  const grouped = groupNodesByModule(entries);

  for (const head of entries.filter(n => n.heading.depth === 1)) {
    descriptors.push({ head, entries: grouped.get(head.api) });
  }
}

descriptors.push(...synthetic);

yield [{ manifest: descriptors.map(({ head }) => head) }];
yield* worker.stream(descriptors);

Comment thread packages/react/package.json Resolved
Comment thread packages/react/src/html/utils/all.mjs Resolved
…t as the site does

From the review, which asked for no extra export. jsx-ast now lists
the manifest's heads in the order the site lists the pages, the
synthetic ones last, so nothing reading its output needs headingSortFn,
and the react package no longer exports getSortedHeadNodes.

merge and createChannel move from core into jsx-ast's utils: jsx-ast and
html are their only callers, and no generator outside the package needs
them. Sending the manifest first, before the pages, would need no merge,
but jsx-ast could then build no page before its whole input arrived: on
the Node.js docs that made the site build 5% slower at 4 threads and 7%
at 6. once, which only core and tests used, is the cache's own again,
and the all.html head helper is inlined.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
@ovflowd

ovflowd commented Nov 20, 2026 •

Copy link
Copy Markdown
Member Author

@avivkeller tried it, it's simpler but 5-7% slower, jsx-ast can't start a page until its input ends. Kept the merge, just private to jsx-ast now, wdyt?

@ovflowd
ovflowd requested a review from avivkeller November 21, 2026 02:31

This branch was successfully deployed

1 active deployment
Preview – api-docs-tooling — d39a4ae1 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants