perf(prerender): reuse each page's HTML render for its navigation data (#501)

## Problem

Static prerendering made two requests per page: one for the HTML, and a
second with `X-VoidPages` to write `_void/pages/*.json`. The loader and
middleware ran twice for every page.

## Fix

Fixes #500

The HTML already embeds the page object in `__VOID_PAGE_DATA__`, so the
prerenderer now writes the JSON from that script and skips the second
request.

- Uses `extractPageDataFromHtml` from `@void/isr/core`, which ISR
already uses to build JSON from page HTML.
- Pages with deferred props still make the second request. Their HTML
has those props missing, because the values are streamed after the page
data script. The prefetch request returns them filled in.
- In practice, defer() is mainly useful for server-rendered pages. A
fully static site rarely needs it, so on most static sites the two
implementations behave the same. IMO, this is an acceptable fix. The
alternative is to
- Island pages and non-page routes have no `__VOID_PAGE_DATA__` script,
so they still get no JSON file.
- The JSON is parsed and stringified again, so the files are
byte-identical to before. The embedded copy escapes `<`, `>` and `&`.

## Results

I ran two benchmarks, once with a 1000-page Void app (no actual network
requests), another with a remote PayloadCMS database.

### 1000-page Void app

Measured with my own 1000-page Void app benchmark, static output. Old
and new code ran alternately in one process on the same build:

| | Before | After |
|---|---|---|
| Requests | 2,002 | 1,001 |
| Prerender phase, Node | 422–477 ms | 380–396 ms (−10% to −19%) |
| Prerender phase, Cloudflare | 848–1,660 ms | 630–1,149 ms (−26% to
−31%) |

On Node, the second request was an in-process call, so a full build
barely changes: 4.99 s before vs 4.64 s after, median of 3, within
noise. The gain is larger on Cloudflare, where each request goes through
the local Workers runtime.

The built output (1,001 HTML and 1,001 JSON files) is byte-identical to
before on both Node and Cloudflare.

### 100-page blog backed by remote Payload CMS

Tested in a more realistic scenario of a 100-post blog backed by a
remote Payload CMS database, where each pre-rendered page fetches from
Payload CMS:

| | Before | After |
|---|---:|---:|
| Build time | 265.00s | 133.31s |
| Payload operations | 1,439 | 722 |

## Tests

- Updated two existing tests that served page data only through the
second request.
- Added one test for deferred pages, which still need the second
request, and for HTML without page data, which gets no JSON file.
- `static-pages` and `node-static` integration tests pass.

## Alternative considered

Another approach handles deferred props in the same single request.
During prerendering, the page handler copies each deferred value into
the page object as it streams, then appends the completed object to the
end of the HTML as a build-only script.

The prerenderer removes that script and writes it as the JSON file. This
avoids the second request even for deferred pages, but it changes
`handlePageGet`, which runs on every page request in every app, and the
appended script has to pass through the app's HTML middleware unchanged.

I prefer to keep the change in build-time code instead. Deferred props
are uncommon in fully static pages, so those pages keeping the second
request costs little.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: LongYinan <github@lyn.one>

Author: 3 people

packages/void/src/prerender-render.ts

@@ -1,6 +1,9 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
+import { extractPageDataFromHtml } from '@void/isr/core';
 import { dirname, isAbsolute, join, relative } from 'pathslash';
 
+const PAGE_DATA_SCRIPT_ID = '__VOID_PAGE_DATA__';
+
 export type PrerenderResult = {
   rendered: Array<string>;
   failed: Array<{ path: string; error: string }>;
@@ -157,14 +160,23 @@ export async function renderPrerenderPaths(
             }
             mkdirSync(dirname(outputPath), { recursive: true });
             writeFileSync(outputPath, html);
-            if (fetchPageData) {
+            // Reuse the page object the HTML embeds for hydration, re-stringified to drop
+            // the \u003c-style escapes. Deferred props embed unresolved, so those pages
+            // still make the X-VoidPages request. HTML without the script gets no JSON.
+            const embeddedPageData = extractPageDataFromHtml(html);
+            let pageData: unknown;
+            if (embeddedPageData !== null) {
+              pageData = JSON.parse(embeddedPageData);
+            } else if (fetchPageData && html.includes(PAGE_DATA_SCRIPT_ID)) {
               const pageDataResponse = await fetchPageData(path);
               if (pageDataResponse.headers.get('X-VoidPages')) {
-                const pageData = await pageDataResponse.json();
-                mkdirSync(dirname(pageDataPath), { recursive: true });
-                writeFileSync(pageDataPath, JSON.stringify(pageData));
+                pageData = await pageDataResponse.json();
               }
             }
+            if (pageData !== undefined) {
+              mkdirSync(dirname(pageDataPath), { recursive: true });
+              writeFileSync(pageDataPath, JSON.stringify(pageData));
+            }
             result.rendered.push(path);
             onResult?.(path, outputFile);
           } catch (err) {

packages/void/test/unit/prerender-render.test.ts

@@ -2,10 +2,13 @@ import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vite-plus/test';
+import { serializePageData } from '../../src/pages/serialize.ts';
 import { renderPrerenderPaths } from '../../src/prerender-render.ts';
 import { createAssetFallback } from '../../src/runtime/routing-worker.ts';
 
 const roots: Array<string> = [];
+const pageHtml = (pageData: unknown) =>
+  `<script id="__VOID_PAGE_DATA__" type="application/json">${serializePageData(pageData)}</script>`;
 const fixture = () => {
   const root = mkdtempSync(join(tmpdir(), 'void-render-pool-'));
   roots.push(root);
@@ -18,36 +21,76 @@ afterEach(() => {
 });
 
 describe('prerender pool', () => {
-  it('bounds overlapping renders, keeps result order, and writes each page data after its HTML', async () => {
+  it('bounds overlapping renders, keeps result order, and writes page data from one render', async () => {
     const root = fixture();
     const paths = Array.from({ length: 12 }, (_, i) => `/page-${i}`);
+    // Characters the embedded script escapes; the JSON file must keep the plain text.
+    const escapedPage = { path: '/page-11', props: { title: '</script><b>a&b</b>\u2028' } };
     let active = 0;
     let peak = 0;
-    const htmlDone = new Set<string>();
+    const dataRequests: Array<string> = [];
     const result = await renderPrerenderPaths(
       paths,
       root,
       async (path) => {
         peak = Math.max(peak, ++active);
         await new Promise((resolve) => setTimeout(resolve, path === '/page-0' ? 12 : 2));
         active--;
-        htmlDone.add(path);
-        return new Response(path, { status: path === '/page-3' ? 503 : 200 });
+        return new Response(pageHtml(path === escapedPage.path ? escapedPage : { path }), {
+          status: path === '/page-3' ? 503 : 200,
+        });
       },
       async (path) => {
-        expect(htmlDone.has(path)).toBe(true);
-        expect(readFileSync(join(root, `${path.slice(1)}.html`), 'utf8')).toBe(path);
+        dataRequests.push(path);
         return Response.json({ path }, { headers: { 'X-VoidPages': 'true' } });
       },
     );
     expect(peak).toBe(4);
     expect(result.rendered).toEqual(paths.filter((path) => path !== '/page-3'));
     expect(result.failed).toEqual([{ path: '/page-3', error: 'HTTP 503' }]);
-    expect(JSON.parse(readFileSync(join(root, '_void/pages/page-11.json'), 'utf8'))).toEqual({
-      path: '/page-11',
+    expect(dataRequests).toEqual([]);
+    expect(readFileSync(join(root, '_void/pages/page-11.json'), 'utf8')).toBe(
+      JSON.stringify(escapedPage),
+    );
+    expect(JSON.parse(readFileSync(join(root, '_void/pages/page-10.json'), 'utf8'))).toEqual({
+      path: '/page-10',
     });
   });
 
+  it('writes resolved page data for deferred pages and none for HTML without page data', async () => {
+    const root = fixture();
+    const dataRequests: Array<string> = [];
+    const result = await renderPrerenderPaths(
+      ['/deferred', '/island'],
+      root,
+      async (path) =>
+        new Response(
+          path === '/deferred'
+            ? pageHtml({ component: 'deferred', props: {}, deferredKeys: { stats: 'stats' } })
+            : '<h1>island</h1>',
+        ),
+      async (path) => {
+        dataRequests.push(path);
+        if (path !== '/deferred') {
+          return new Response('<h1>island</h1>');
+        }
+        expect(existsSync(join(root, 'deferred.html'))).toBe(true);
+        return Response.json(
+          { component: 'deferred', props: { stats: 1 }, deferredKeys: { stats: 'stats' } },
+          { headers: { 'X-VoidPages': 'true' } },
+        );
+      },
+    );
+    expect(result).toEqual({ rendered: ['/deferred', '/island'], failed: [] });
+    expect(dataRequests).toEqual(['/deferred']);
+    expect(JSON.parse(readFileSync(join(root, '_void/pages/deferred.json'), 'utf8'))).toEqual({
+      component: 'deferred',
+      props: { stats: 1 },
+      deferredKeys: { stats: 'stats' },
+    });
+    expect(existsSync(join(root, '_void/pages/island.json'))).toBe(false);
+  });
+
   it.each([
     ['/', '/index'],
     ['/same', '/same'],
@@ -122,15 +165,19 @@ describe('prerender pool', () => {
     const root = fixture();
     const clientDir = join(root, 'client');
     const fetched: Array<string> = [];
+    const dataRequests: Array<string> = [];
     const outputs: Array<[string, string, string | undefined]> = [];
     const result = await renderPrerenderPaths(
       ['/blog/../../escape', '/ok', '/../client/data-escape'],
       clientDir,
       async (path) => {
         fetched.push(path);
-        return new Response('<h1>page</h1>');
+        return new Response(pageHtml({ path }));
+      },
+      async (path) => {
+        dataRequests.push(path);
+        return Response.json({ path }, { headers: { 'X-VoidPages': 'true' } });
       },
-      async (path) => Response.json({ path }, { headers: { 'X-VoidPages': 'true' } }),
       (path, outputFile, error) => outputs.push([path, outputFile, error]),
     );
     const error = 'prerender path resolves outside the output directory';
@@ -140,12 +187,13 @@ describe('prerender pool', () => {
       { path: '/../client/data-escape', error },
     ]);
     expect(fetched).toEqual(['/ok']);
+    expect(dataRequests).toEqual([]);
     expect(outputs).toContainEqual(['/blog/../../escape', 'blog/../../escape.html', error]);
     expect(existsSync(join(root, 'escape.html'))).toBe(false);
     expect(existsSync(join(clientDir, '_void/escape.json'))).toBe(false);
     expect(existsSync(join(clientDir, 'data-escape.html'))).toBe(false);
     expect(existsSync(join(clientDir, '_void/client/data-escape.json'))).toBe(false);
-    expect(readFileSync(join(clientDir, 'ok.html'), 'utf8')).toBe('<h1>page</h1>');
+    expect(readFileSync(join(clientDir, 'ok.html'), 'utf8')).toBe(pageHtml({ path: '/ok' }));
     expect(JSON.parse(readFileSync(join(clientDir, '_void/pages/ok.json'), 'utf8'))).toEqual({
       path: '/ok',
     });