Skip to content

Commit eb272cd

Browse files
authored
perf(vite): memoize dev prerender renders keyed by router-instance identity (#654) (#662)
The /__rsc_prerender endpoint re-rendered the full segment chain (and re-ran getParams) on every request. Results are now cached per router instance: the per-request entry re-import re-runs createRouter() exactly when the HMR chain was invalidated, so instance identity IS the edit generation (WeakMap; stale generations GC). One render warms both the main and intercept variant keys; x-rango-prerender-cache: HIT|MISS reports the outcome. The Cloudflare temp-runner path now re-imports the entry per request too, fixing handler-only-edit staleness (files without urls()/createRouter() never triggered a temp-registry refresh, so edits served stale prerender content until a route-file edit).
1 parent da524c2 commit eb272cd

10 files changed

Lines changed: 636 additions & 19 deletions

File tree

‎packages/rangojs-router/docs/internal/feature-file-map.md‎

Lines changed: 2 additions & 2 deletions
Large diffs are not rendered by default.

‎packages/rangojs-router/docs/internal/feature-map.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,12 @@ Router option `theme`, `ThemeProvider` integration on server and client, `ThemeS
290290
- `buildEnv` Vite plugin option for build-time `ctx.env` access (KV, D1, etc.)
291291
- `"auto"` mode calls `wrangler.getPlatformProxy()` for Cloudflare presets
292292
- Applies to both production build and dev `/__rsc_prerender` evaluation
293+
- Dev `/__rsc_prerender` memoizes rendered payloads between HMR edits, keyed by
294+
router-instance identity (`vite/discovery/dev-prerender-cache.ts`, issue
295+
#654): per-request entry re-import makes instance identity the HMR
296+
generation (on cloudflare the temp-runner re-import also fixes
297+
handler-only-edit staleness); one render warms main + intercept variant
298+
keys; `x-rango-prerender-cache: HIT | MISS` response header
293299
- Build-time render errors surface to the build instead of baking an error page
294300
(issue #587): `ResolveSegmentOptions.throwOnError` (set only by the prerender
295301
path) re-throws through `matchForPrerender`. `prerender.onError` Vite plugin

‎packages/rangojs-router/docs/prerender-api-design.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -207,8 +207,28 @@ a pathname) and adds `passthrough=1` for `Passthrough()` routes so unknown
207207
params defer to the live handler in dev, mirroring production. `intercept=1`
208208
requests the intercept (modal slot) variant.
209209

210-
In Node.js dev mode, `__PRERENDER_DEV_URL` is undefined and handlers run
211-
in-process.
210+
The Node preset sets `__PRERENDER_DEV_URL` too — both presets round-trip
211+
through the endpoint (a loopback fetch in the Node preset), so prerender
212+
rendering always happens Node-side with the build env available.
213+
214+
The endpoint memoizes rendered payloads between HMR edits (#654), keyed by
215+
router-instance identity (`vite/discovery/dev-prerender-cache.ts`). It
216+
re-imports the user's entry through a module runner on every request — the
217+
Node preset on the main RSC environment, the Cloudflare preset on the shared
218+
temp Node server — so an edit anywhere in the entry → router → urls → handler
219+
chain re-runs `createRouter()`, registers a NEW router instance, and thereby
220+
strands the old instance's cache bucket (a WeakMap: stale generations are
221+
garbage-collected). A warm request is a module-cache hit plus a Map lookup;
222+
one render warms both the main and `intercept=1` variant keys.
223+
`x-rango-prerender-cache: HIT | MISS` reports the outcome per response.
224+
Between edits the endpoint serves frozen results — matching production, where
225+
artifacts freeze at build time — so `getParams()`/handler side effects (fs,
226+
DB via buildEnv) run once per edit generation, not once per request. The
227+
per-request re-import on the Cloudflare temp server is also the freshness
228+
fix for handler-only edits (files without `urls()`/`createRouter()` that the
229+
main watcher's route-file sniff ignores): the temp server's own watcher
230+
invalidates its graph, and the re-import re-evaluates exactly the dirty
231+
subgraph.
212232

213233
---
214234

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
import { expect, test } from "@playwright/test";
2+
import { useFixture } from "./fixture";
3+
4+
/**
5+
* Dev prerender result cache (#654): /__rsc_prerender memoizes rendered
6+
* payloads keyed by router-instance identity, so repeated requests between
7+
* HMR edits skip the module re-import render and getParams work. The
8+
* `x-rango-prerender-cache` header exposes HIT/MISS for observability.
9+
*
10+
* Determinism note: the runtime dev store ALWAYS sends `routeName`
11+
* (see prerender-api-design.md, Dev Mode), so these requests deliberately
12+
* OMIT it — the cache key's routeName dimension makes that key unreachable
13+
* by any page-navigation warming from sibling suites sharing the dev server.
14+
*
15+
* The edit-invalidation half of the contract (edit → MISS + fresh content)
16+
* lives in prerender-hmr.test.ts (local-only, file-watcher territory).
17+
*/
18+
19+
test.describe("prerender dev cache", () => {
20+
// isolatedServer: the MISS/HIT sequence needs a dev server whose endpoint
21+
// cache no other suite (or a sibling checkout's shared-port server) can
22+
// touch. The fixture spawns a dedicated dev server on a discovered port.
23+
const f = useFixture({
24+
root: "./e2e/test-app",
25+
mode: "dev",
26+
isolatedServer: true,
27+
});
28+
29+
test("endpoint serves MISS then HIT with a byte-identical body", async ({
30+
request,
31+
}) => {
32+
const url = f.url("/__rsc_prerender?pathname=/docs");
33+
34+
// First-ever request for this key on this server: deterministically a
35+
// MISS regardless of any concurrent invalidation (a churned identity
36+
// still has no cached body for the key).
37+
const first = await request.get(url);
38+
expect(first.status()).toBe(200);
39+
expect(first.headers()["x-rango-prerender-cache"]).toBe("MISS");
40+
const firstBody = await first.text();
41+
42+
// The payload is the real prerender wire format, not an error shape.
43+
const parsed = JSON.parse(firstBody);
44+
expect(Array.isArray(parsed.segments)).toBe(true);
45+
expect(parsed.segments.length).toBeGreaterThan(0);
46+
47+
// HIT via paired poll: request twice per attempt and require the second
48+
// response to be a HIT byte-identical to the first. A legitimate
49+
// identity churn between the pair (dep-optimizer re-optimization, a
50+
// sibling process touching a watched file) retries the pair; a broken
51+
// cache never returns HIT and the poll times out.
52+
await expect
53+
.poll(
54+
async () => {
55+
const a = await request.get(url);
56+
const aBody = await a.text();
57+
const b = await request.get(url);
58+
const bBody = await b.text();
59+
return b.headers()["x-rango-prerender-cache"] === "HIT" &&
60+
bBody === aBody
61+
? "HIT-identical"
62+
: `retry(${b.headers()["x-rango-prerender-cache"]})`;
63+
},
64+
{ timeout: 15000 },
65+
)
66+
.toBe("HIT-identical");
67+
});
68+
69+
test("one render warms the intercept variant key too", async ({
70+
request,
71+
}) => {
72+
// /docs/getting-started: fresh pathname for this test (still no
73+
// routeName, so no sibling warming). The main-variant render must warm
74+
// intercept=1 as well — matchForPrerender computes intercept segments
75+
// unconditionally, so the second variant costs no extra render.
76+
//
77+
// Paired poll: each attempt renders/warms via the main variant, then
78+
// requests the intercept variant. On the (typical) first attempt an
79+
// intercept HIT can only come from the main render's warming — the
80+
// strong claim. Later attempts only occur under a concurrent identity
81+
// churn; the precise both-keys-from-one-render semantics are pinned
82+
// deterministically by the dev-prerender-cache unit tests.
83+
const mainUrl = f.url("/__rsc_prerender?pathname=/docs/getting-started");
84+
const interceptUrl = f.url(
85+
"/__rsc_prerender?pathname=/docs/getting-started&intercept=1",
86+
);
87+
await expect
88+
.poll(
89+
async () => {
90+
const main = await request.get(mainUrl);
91+
if (main.status() !== 200) return `main-${main.status()}`;
92+
const intercept = await request.get(interceptUrl);
93+
if (intercept.status() !== 200) return `int-${intercept.status()}`;
94+
return intercept.headers()["x-rango-prerender-cache"];
95+
},
96+
{ timeout: 15000 },
97+
)
98+
.toBe("HIT");
99+
});
100+
});
101+
102+
test.describe("prerender dev cache absent (production)", () => {
103+
const f = useFixture({
104+
root: "./e2e/test-app",
105+
mode: "build",
106+
isolatedServer: true,
107+
});
108+
109+
test("prerendered route serves the frozen artifact with no dev-cache header; the dev endpoint does not exist", async ({
110+
request,
111+
}) => {
112+
const page = await request.get(f.url("/docs"));
113+
expect(page.status()).toBe(200);
114+
expect(page.headers()["x-rango-prerender-cache"]).toBeUndefined();
115+
expect(await page.text()).toContain("pre-rendered documentation content");
116+
117+
// Production serves prerendered payloads from the built manifest inside
118+
// the worker — the dev endpoint must not exist (and must not leak the
119+
// dev-cache header) in a production serve.
120+
const endpoint = await request.get(
121+
f.url("/__rsc_prerender?pathname=/docs"),
122+
);
123+
expect(endpoint.headers()["x-rango-prerender-cache"]).toBeUndefined();
124+
expect(endpoint.headers()["content-type"] ?? "").not.toContain(
125+
"application/json",
126+
);
127+
});
128+
});

‎packages/rangojs-router/e2e/prerender-hmr.test.ts‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,4 +127,67 @@ test.describe.serial("prerender-hmr", () => {
127127
{ timeout: 15000 },
128128
);
129129
});
130+
131+
// -- Endpoint-level cache invalidation (#654) ---------------------------
132+
// The identity-keyed dev prerender cache must drop on an HMR edit: the
133+
// entry chain re-evaluates, createRouter() registers a NEW instance, and
134+
// the next endpoint request is a MISS carrying the fresh content. This is
135+
// the precise wire-level counterpart of the page-level tests above.
136+
137+
test("endpoint cache: warm HIT, edit handler, next request is MISS with fresh content", async ({
138+
request,
139+
}) => {
140+
// No routeName: the runtime dev store always sends one, so the r=""
141+
// cache key belongs to direct endpoint tests only. warm1 makes no
142+
// MISS/HIT assumption in case a sibling direct test already warmed it.
143+
const url = f.url("/__rsc_prerender?pathname=/docs");
144+
145+
const warm1 = await request.get(url);
146+
expect(warm1.status()).toBe(200);
147+
const warm2 = await request.get(url);
148+
expect(warm2.headers()["x-rango-prerender-cache"]).toBe("HIT");
149+
expect(await warm2.text()).toContain(
150+
"This is pre-rendered documentation content.",
151+
);
152+
153+
const modified = prerenderOriginal.replace(
154+
"This is pre-rendered documentation content.",
155+
"Cache-invalidated pre-rendered content.",
156+
);
157+
fs.writeFileSync(prerenderPath, modified);
158+
159+
// Poll: the watcher must invalidate the chain, the re-import must
160+
// re-register the router, and the endpoint must re-render fresh.
161+
await expect
162+
.poll(
163+
async () => {
164+
const res = await request.get(url);
165+
const body = await res.text();
166+
return body.includes("Cache-invalidated pre-rendered content.")
167+
? res.headers()["x-rango-prerender-cache"]
168+
: "stale";
169+
},
170+
{ timeout: 15000 },
171+
)
172+
.toBe("MISS");
173+
174+
// And the fresh body re-memoizes under the new identity. Poll rather
175+
// than asserting the very next request: the edited file contains urls(),
176+
// so the route-file watcher's DEBOUNCED rediscovery re-evaluates the
177+
// chain once more shortly after the immediate HMR invalidation — that
178+
// trailing cycle produces one more legitimate MISS before the identity
179+
// stabilizes and requests converge to HIT.
180+
await expect
181+
.poll(
182+
async () => {
183+
const res = await request.get(url);
184+
const body = await res.text();
185+
return body.includes("Cache-invalidated pre-rendered content.")
186+
? res.headers()["x-rango-prerender-cache"]
187+
: "stale";
188+
},
189+
{ timeout: 15000 },
190+
)
191+
.toBe("HIT");
192+
});
130193
});

0 commit comments

Comments
 (0)