Start: prerender.concurrency does not parallelize CPU-bound page rendering #8483
Send to my agentWhich project does this relate to?#
Start
Describe the bug#
In the tested version, increasing prerender.concurrency does not parallelize CPU-bound page rendering. The prerenderer sends requests to one preview server; overlapping requests do not provide parallel JavaScript CPU execution.
The updated reproduction distinguishes this from async waiting: the CPU workload stays close to its concurrency-1 baseline, while an async-wait control gets substantially faster. The concurrency setting is effective for overlapping waits.
An official way to spread CPU-bound prerendering across preview workers/processes, or clearer documentation of this limitation, would help sites with many CPU-bound pages.
Complete minimal reproducer#
https://github.com/R4ULtv/tanstack-start-prerender-concurrency
Recorded benchmark revision: ab7e13a.
Steps to Reproduce the Bug#
- Clone the repository and run
npm ci(Node.js 22.18+). - Run
npm run bench. - Open
benchmark/results/report.htmlto inspect all cases, individual runs, medians, and ranges.
The benchmark runs 80 measured builds plus four warmups:
- CPU workload: 100, 500, and 1,000 pages; the original 500,000 synchronous arithmetic iterations and 200 rendered rows per page.
- Async-wait control: 100 pages; a 15 ms timer followed by 200 inexpensive deterministic rows. This tests overlap, not real network/storage performance.
- Concurrency 1, 2, 4, 8, and 16, with four repeats per condition.
- Fresh Node processes and a deleted
distper build; rotated forward/reverse run orders balance early and late positions. - Prerender time measured separately from full-build time. Identical per-page logging is suppressed in every condition.
Settings are constants in benchmark/run.mjs. npm run build still provides a single CPU-workload reproduction build.
Benchmark results#
Median prerender-phase times on an Apple M4, 10 logical CPUs, Node.js 24.22.2:
| Concurrency | CPU: 1,000 pages | Async wait: 100 pages |
|---|---|---|
| 1 | 21.258 s | 1.974 s |
| 2 | 21.376 s | 1.058 s |
| 4 | 20.857 s | 0.565 s |
| 8 | 21.123 s | 0.346 s |
| 16 | 20.849 s | 0.232 s |
Concurrency 16 vs 1 measured 1.02× speedup for the CPU case and 8.50× for the async control. Each uses its own workload/page-count baseline; these are not equal-work comparisons between the two workloads.
All runs verified exact request paths/counts and generated output. The benchmark uses trailingSlash: 'always' with canonical slash-ended paths: exactly one 200 response per page and zero redirects, excluding the separate overhead tracked in #8850. No requests are rewritten.
Every page ID and all rendered row values are checked. Complete HTML hashes match across concurrency settings/repeats after normalizing only serialized match-update timestamps; other output assets match byte-for-byte within each case.
These repeated measurements replace the original three single-run build-time samples. They retain all runs and are specific to this synthetic local Node workload. Dependencies/OS caches remain warm; this was not a dedicated-machine experiment. No Cloudflare adapter, deployment, or custom worker pool was measured.
Expected behavior#
An option such as prerender.workers could distribute CPU-bound rendering across several preview servers/workers on multi-core machines. Alternatively, document clearly that request concurrency overlaps asynchronous work and does not itself provide parallel JavaScript rendering.
Screenshots or Videos#
- Self-contained HTML benchmark report — download/open for interactive workload and timing selectors.
- Raw measurements, methodology, and verification metadata (JSON)
- Every measured run (CSV)
Platform#
@tanstack/react-start: 1.168.57@tanstack/react-router: 1.170.38@tanstack/start-plugin-core(transitive): 1.171.47- React / React DOM: 19.3.0
- Vite: 8.3.0
- Node.js: 24.22.2
- macOS / Darwin 24.6.0, arm64; Apple M4, 10 logical CPUs, 16 GiB RAM
- Default Node preview server; no deployment adapter
- Versions are pinned to the original lockfile, so this update changes the experiment rather than upgrading the framework.
Additional context#
My production app has approximately 19k prerendered pages. In an earlier, separate experiment, splitting pages across four preview processes reduced prerendering from roughly 110–150 seconds to approximately 45 seconds. That workaround depended on internals; it is historical context and was not retested by this benchmark.
- Related: #8430, preview resource isolation.
- Trailing-slash redirect overhead is now tracked separately in #8850.
- Earlier attempts with several local workerd instances hit
SQLITE_BUSYon shared.wrangler/stateuntil persistence was disabled per instance; an official multi-preview solution may need to coordinate that state.
Prepared with AI assistance. The reproduction, repeated benchmarks, request/output checks, clean installation, normal build, and type checks were executed locally.
R4ULtv(GitHub profile, opens in a new tab) changed the title
Sign in to join this conversation.
I have an implementation ready. It adds an option, so I'd like a maintainer to agree on the API before I open a PR.
Cause: the Vite prerender handler starts one preview server and sends every request to it.
concurrencyoverlaps the requests, but SSR is CPU-bound, so rendering stays on one core. Severalvite.preview()servers in the same process don't fix it either: plugins with module-level state are shared between them. For example,@cloudflare/vite-pluginkeeps one workerd per process. I tried it: no speedup, andERR_SERVER_NOT_RUNNINGon close.Proposal: a
prerender.workersoption (Vite only, default1, which keeps today's single in-process server).workers > 1, each worker is a forked process that runs its ownvite.preview()and reports its URL over IPC.TSS_PRERENDER_WORKERset to its index, so a Vite config can avoid shared resources. Cloudflare needs this: workers sharing.wrangler/statefail withSQLITE_BUSY, and they all bind inspector port 9229. The docs showcloudflare({ ...(process.env.TSS_PRERENDER_WORKER !== undefined && { persistState: false, inspectorPort: false }) }).Results (20,302 pages,
@cloudflare/vite-plugin, using the same logic as a pnpm patch):Local: 116s with one server, 62s with
workers: 4.Cloudflare Workers Builds (4 vCPU): prerender took 260s before and 136s with
workers: 3.Branch: https://github.com/R4ULtv/router/compare/main...feat/prerender-workers (one commit, with schema, React/Solid docs, unit tests and a changeset)
test:unit,test:eslint,test:typesandbuildpass for@tanstack/start-plugin-core.start-basic-staticwithworkers: 3prerenders the same 37 pages and leaves no worker processes behind.Does this API work for you? If it does, I'll open the PR.
Prepared with AI assistance (Claude Code).