Skip to content
Source
Sign inSign up
TanStack/router

Start: prerender.concurrency does not parallelize CPU-bound page rendering #8483

Send to my agent
OpenR4ULtv(GitHub profile, opens in a new tab) opened this issue 1 comment

Which 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

  1. Clone the repository and run npm ci (Node.js 22.18+).
  2. Run npm run bench.
  3. Open benchmark/results/report.html to 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 dist per 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:

ConcurrencyCPU: 1,000 pagesAsync wait: 100 pages
121.258 s1.974 s
221.376 s1.058 s
420.857 s0.565 s
821.123 s0.346 s
1620.849 s0.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

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_BUSY on shared .wrangler/state until 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.

  1. R4ULtv(GitHub profile, opens in a new tab) changed the title

  2. 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. concurrency overlaps the requests, but SSR is CPU-bound, so rendering stays on one core. Several vite.preview() servers in the same process don't fix it either: plugins with module-level state are shared between them. For example, @cloudflare/vite-plugin keeps one workerd per process. I tried it: no speedup, and ERR_SERVER_NOT_RUNNING on close.

    Proposal: a prerender.workers option (Vite only, default 1, which keeps today's single in-process server).

    • With workers > 1, each worker is a forked process that runs its own vite.preview() and reports its URL over IPC.
    • Each request goes to the least busy worker. Responses are buffered, so a worker counts as busy until its page has finished rendering.
    • A redirect to a worker's own origin is rewritten to the primary origin, so the existing same-origin check still follows it.
    • Each worker process has TSS_PRERENDER_WORKER set to its index, so a Vite config can avoid shared resources. Cloudflare needs this: workers sharing .wrangler/state fail with SQLITE_BUSY, and they all bind inspector port 9229. The docs show cloudflare({ ...(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:types and build pass for @tanstack/start-plugin-core. start-basic-static with workers: 3 prerenders 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).

Sign in to join this conversation.