Skip to content

Commit 291c724

Browse files
authored
perf(vite): ship route manifest as a workerd Text module on cloudflare builds (refs #665) (#710)
At route scale the per-router manifest chunk inlines trie + precomputedEntries as JSON.parse('<literal>'). That costs the first request twice — the isolate/process lexes and compiles the multi-MB JS source literal before JSON.parse runs — and ships bloated, because the build minifier re-quotes the literal to double quotes, escaping every JSON " (measured 5.71MB vs 4.64MB un-escaped at 26k routes). The only way to fix both is to keep the JSON out of JavaScript source, as a raw asset file that never passes through the JS minifier/compiler. On cloudflare that is a workerd Text module: importing a staged .txt hands the isolate the raw un-escaped bytes as a string with no compile pass (measured ~17% / ~88ms cold first-hit on a real edge deploy at 26k, and it shrinks the worker upload against the hard size limit). The CF vite plugin types .txt as Text; wrangler's default rules type **/*.txt as Text for deploy and dev. Scoped to cloudflare deliberately. A Text module is the only no-JS byte channel needing no filesystem, and cloudflare is where it pays (per- request cold isolates, upload-size limit). node/vercel keep the inline literal: an efficient channel there needs fs (a raw asset read), whose fragility isn't worth a large-app-only win that Fluid Compute amortizes and that essentially no real app reaches. Verified that ?raw is NOT a node/vercel shortcut — in this build it inlines the JSON as a double- quoted compiled JS string literal (same bloat, same compile as inline). Gating: build mode only (dev rebuilds per HMR, parse cost irrelevant); 512KB serialized-payload threshold (~2500 routes — the crossover where the benefit clears the extra artifact; the long tail of normal apps stays byte-identical inline); RANGO_MANIFEST_TEXT=0 forces inline, =1 forces the Text module and bypasses the threshold. Staged filename carries an FNV-1a hash of the router id so distinct ids that sanitize to the same string ("a/b" vs "a.b") don't overwrite each other. Coverage: unit tests over the gate matrix (cloudflare->Text above threshold, inline below/dev, node+vercel always inline even when forced, collision-safe filenames, un-escaped staged payload); cloudflare-basic production e2e (forced via RANGO_MANIFEST_TEXT=1 since its 15KB manifest is below threshold — whole prod suite dogfoods the Text channel on real workerd, asserts the .txt exists, is imported, and is raw un-escaped JSON). bench/{cold-only,edge-cold}.ts A/B harnesses retained.
1 parent d429fcd commit 291c724

6 files changed

Lines changed: 435 additions & 2 deletions

File tree

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
import { describe, it, expect, beforeEach, afterEach } from "vitest";
2+
import {
3+
mkdtempSync,
4+
readFileSync,
5+
existsSync,
6+
rmSync,
7+
readdirSync,
8+
} from "node:fs";
9+
import { tmpdir } from "node:os";
10+
import { join } from "node:path";
11+
import { generatePerRouterModule } from "../virtual-module-codegen";
12+
import { createDiscoveryState, type DiscoveryState } from "../state";
13+
14+
// A trie whose serialized form clears MANIFEST_EXTERNALIZE_THRESHOLD (512KB).
15+
// ~90 bytes/leaf, so 8000 leaves ~= 700KB. SMALL stays well under.
16+
function bigTrie(n: number) {
17+
const s: Record<string, unknown> = {};
18+
for (let i = 0; i < n; i++) {
19+
s[`route-segment-number-${i}`] = {
20+
r: {
21+
n: `route.name.number.${i}`,
22+
sp: "",
23+
a: ["M0L0", `M0L0R${i}`],
24+
pa: ["locale", "id"],
25+
},
26+
};
27+
}
28+
return { s };
29+
}
30+
const BIG = bigTrie(8000);
31+
const SMALL = bigTrie(3);
32+
const ENTRIES = [{ staticPrefix: "", routes: { home: "/" } }];
33+
34+
let tmpRoot: string;
35+
let savedOverride: string | undefined;
36+
37+
beforeEach(() => {
38+
tmpRoot = mkdtempSync(join(tmpdir(), "rango-vmc-"));
39+
savedOverride = process.env.RANGO_MANIFEST_TEXT;
40+
delete process.env.RANGO_MANIFEST_TEXT;
41+
});
42+
43+
afterEach(() => {
44+
rmSync(tmpRoot, { recursive: true, force: true });
45+
if (savedOverride === undefined) delete process.env.RANGO_MANIFEST_TEXT;
46+
else process.env.RANGO_MANIFEST_TEXT = savedOverride;
47+
});
48+
49+
function makeState(
50+
preset: "node" | "cloudflare" | "vercel",
51+
opts: { isBuildMode?: boolean; trie?: unknown } = {},
52+
routerId = "r1",
53+
): DiscoveryState {
54+
const s = createDiscoveryState(undefined, { preset });
55+
s.projectRoot = tmpRoot;
56+
s.isBuildMode = opts.isBuildMode ?? true;
57+
s.perRouterManifests.push({ id: routerId, routeManifest: { home: "/" } });
58+
s.perRouterManifestDataMap.set(routerId, { home: "/" });
59+
s.perRouterTrieMap.set(routerId, opts.trie ?? BIG);
60+
s.perRouterPrecomputedMap.set(routerId, ENTRIES);
61+
return s;
62+
}
63+
64+
const ragoDir = (root: string) => join(root, "node_modules", ".rango");
65+
66+
describe("generatePerRouterModule — cloudflare Text module channel", () => {
67+
it("emits a .txt Text-module import above the threshold and stages un-escaped JSON", () => {
68+
const code = generatePerRouterModule(makeState("cloudflare"), "r1");
69+
70+
expect(code).toContain("import __manifestJson from");
71+
expect(code).toContain(".txt");
72+
expect(code).toContain("export const trie = __manifestData.t;");
73+
expect(code).toContain(
74+
"export const precomputedEntries = __manifestData.p;",
75+
);
76+
expect(code).not.toContain("export const trie = JSON.parse(");
77+
expect(code).not.toContain("?raw");
78+
expect(code).not.toContain("readFileSync");
79+
80+
const files = readdirSync(ragoDir(tmpRoot));
81+
expect(files).toHaveLength(1);
82+
const staged = readFileSync(join(ragoDir(tmpRoot), files[0]!), "utf8");
83+
// Staged raw and un-escaped (no \\" bloat) — this is the whole point.
84+
expect(staged.startsWith('{"t":')).toBe(true);
85+
expect(JSON.parse(staged)).toEqual({ t: BIG, p: ENTRIES });
86+
});
87+
88+
it("distinct router ids never share a staged file (collision-safe filename)", () => {
89+
const s1 = makeState("cloudflare", {}, "a/b");
90+
// add a second router with a colliding sanitized id into the same state
91+
s1.perRouterManifests.push({ id: "a.b", routeManifest: { home: "/" } });
92+
s1.perRouterManifestDataMap.set("a.b", { home: "/" });
93+
s1.perRouterTrieMap.set("a.b", BIG);
94+
s1.perRouterPrecomputedMap.set("a.b", ENTRIES);
95+
generatePerRouterModule(s1, "a/b");
96+
generatePerRouterModule(s1, "a.b");
97+
// Two distinct staged files, not one overwrite.
98+
expect(readdirSync(ragoDir(tmpRoot))).toHaveLength(2);
99+
});
100+
101+
it("below the threshold keeps the inline literal", () => {
102+
const code = generatePerRouterModule(
103+
makeState("cloudflare", { trie: SMALL }),
104+
"r1",
105+
);
106+
expect(code).toContain("export const trie = JSON.parse(");
107+
expect(code).not.toContain(".txt");
108+
expect(existsSync(ragoDir(tmpRoot))).toBe(false);
109+
});
110+
111+
it("dev keeps the inline literal even above the threshold", () => {
112+
const code = generatePerRouterModule(
113+
makeState("cloudflare", { isBuildMode: false }),
114+
"r1",
115+
);
116+
expect(code).toContain("export const trie = JSON.parse(");
117+
expect(code).not.toContain(".txt");
118+
});
119+
120+
it("RANGO_MANIFEST_TEXT=1 emits the Text module below the threshold", () => {
121+
process.env.RANGO_MANIFEST_TEXT = "1";
122+
const code = generatePerRouterModule(
123+
makeState("cloudflare", { trie: SMALL }),
124+
"r1",
125+
);
126+
expect(code).toContain(".txt");
127+
expect(code).toContain("import __manifestJson from");
128+
});
129+
130+
it("RANGO_MANIFEST_TEXT=0 forces the inline literal above the threshold", () => {
131+
process.env.RANGO_MANIFEST_TEXT = "0";
132+
const code = generatePerRouterModule(makeState("cloudflare"), "r1");
133+
expect(code).toContain("export const trie = JSON.parse(");
134+
expect(code).not.toContain(".txt");
135+
});
136+
});
137+
138+
describe("generatePerRouterModule — node/vercel keep the inline literal", () => {
139+
for (const preset of ["node", "vercel"] as const) {
140+
it(`${preset}: inline literal above the threshold (no channel off cloudflare)`, () => {
141+
const code = generatePerRouterModule(makeState(preset), "r1");
142+
expect(code).toContain("export const trie = JSON.parse(");
143+
expect(code).not.toContain(".txt");
144+
expect(code).not.toContain("?raw");
145+
expect(code).not.toContain("readFileSync");
146+
expect(existsSync(ragoDir(tmpRoot))).toBe(false);
147+
});
148+
149+
it(`${preset}: RANGO_MANIFEST_TEXT=1 does NOT force a channel (Text is cloudflare-only)`, () => {
150+
process.env.RANGO_MANIFEST_TEXT = "1";
151+
const code = generatePerRouterModule(makeState(preset), "r1");
152+
expect(code).toContain("export const trie = JSON.parse(");
153+
expect(code).not.toContain(".txt");
154+
});
155+
}
156+
});

‎packages/rangojs-router/src/vite/discovery/virtual-module-codegen.ts‎

Lines changed: 112 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,25 @@
55
* per-router virtual modules used by the load() hook.
66
*/
77

8+
import { mkdirSync, writeFileSync } from "node:fs";
89
import { dirname, basename, join } from "node:path";
910
import { jsonParseExpression } from "../utils/manifest-utils.js";
1011
import { VIRTUAL_ROUTES_MANIFEST_ID } from "./state.js";
1112
import type { DiscoveryState } from "./state.js";
1213

14+
/**
15+
* Serialized-payload size (bytes) at or above which the trie/precomputedEntries
16+
* are shipped through a runtime channel (Text module / `?raw` import) instead of
17+
* an inline `JSON.parse` literal (issue #665). 512KB is ~2500 routes — the
18+
* crossover where the channel's benefit (removing the JS compile on cloudflare,
19+
* reclaiming ~19% escaping bloat everywhere) clears the cost of an extra
20+
* artifact. Below it the inline literal wins (sub-millisecond compile, ~0 gain),
21+
* so the whole long tail of normal apps stays byte-identical. The compile/parse
22+
* cost tracks bytes, not route count, so this stays a byte threshold.
23+
* RANGO_MANIFEST_TEXT=1 bypasses it.
24+
*/
25+
const MANIFEST_EXTERNALIZE_THRESHOLD = 512 * 1024;
26+
1327
/**
1428
* Generate the code for the main virtual:rsc-router/routes-manifest module.
1529
*/
@@ -137,6 +151,22 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
137151
return `// Route manifest will be populated at runtime`;
138152
}
139153

154+
/**
155+
* Deterministic short hash (FNV-1a, base36) used to disambiguate staged
156+
* manifest filenames. The sanitized `safeId` alone collapses distinct router
157+
* ids — e.g. "a/b" and "a.b" both sanitize to "a_b" — which in a multi-router
158+
* build would overwrite one router's staged manifest with another's. Appending
159+
* a hash of the ORIGINAL id keeps them distinct.
160+
*/
161+
function shortHash(input: string): string {
162+
let h = 0x811c9dc5;
163+
for (let i = 0; i < input.length; i++) {
164+
h ^= input.charCodeAt(i);
165+
h = Math.imul(h, 0x01000193);
166+
}
167+
return (h >>> 0).toString(36);
168+
}
169+
140170
/**
141171
* Generate the code for a per-router virtual module.
142172
*/
@@ -171,13 +201,93 @@ export function generatePerRouterModule(
171201
lines.push(`export const manifest = ${jsonParseExpression(manifest)};`);
172202
}
173203
}
174-
if (trie) {
204+
const hasTrie = !!trie;
205+
const hasEntries = !!entries && entries.length > 0;
206+
207+
// The trie + precomputedEntries are the largest generated data. Inlined as a
208+
// `JSON.parse('<literal>')` in the JS chunk, the isolate/process must LEX and
209+
// compile that multi-MB source literal on first request before JSON.parse even
210+
// runs — pure overhead, since it is data, not logic (issue #665). It also
211+
// ships bloated: the build minifier re-quotes the literal to double quotes,
212+
// escaping every JSON `"` as `\"` (measured 5.71MB vs 4.64MB un-escaped at 26k
213+
// routes).
214+
//
215+
// The ONLY way to fix both is to keep the JSON out of JavaScript source — as a
216+
// raw asset file that never passes through the JS minifier/compiler. On
217+
// cloudflare that is a workerd Text module: import the staged `.txt` and the
218+
// isolate gets the raw un-escaped bytes as a string with no compile pass
219+
// (measured ~17% / ~88ms cold first-hit on a real edge deploy at 26k, and it
220+
// shrinks the worker upload). The CF vite plugin types `.txt` as Text;
221+
// wrangler's default rules type **/*.txt as Text for deploy and dev.
222+
//
223+
// Scoped to cloudflare deliberately. A Text module is the only no-JS byte
224+
// channel that needs no filesystem, and cloudflare is where it pays: edge cold
225+
// isolates spin up per-request under load and on every deploy, and Workers
226+
// have a hard upload-size limit. node/vercel fall through to the inline
227+
// literal below — an efficient runtime channel there needs `fs` (a raw asset
228+
// read), whose fragility (asset co-location, runtime ENOENT) is not worth a
229+
// large-app-only win that Fluid Compute amortizes and that essentially no real
230+
// app reaches. `?raw` is NOT an option: in this build it inlines the JSON as a
231+
// (double-quoted, compiled) JS string literal — same bloat, same compile as
232+
// the inline form, plus a staged file for nothing.
233+
//
234+
// Build mode only (dev rebuilds the manifest per HMR; parse cost is
235+
// irrelevant). Below MANIFEST_EXTERNALIZE_THRESHOLD the inline literal wins.
236+
// RANGO_MANIFEST_TEXT overrides: "0" forces inline, "1" forces the Text module
237+
// and bypasses the threshold (used by the cloudflare-basic dogfood e2e, whose
238+
// real manifest is below the threshold).
239+
const preset = state.opts?.preset ?? "node";
240+
const override = process.env.RANGO_MANIFEST_TEXT;
241+
const payload = manifestPayload(trie, hasTrie, entries, hasEntries);
242+
const payloadJson = hasTrie || hasEntries ? JSON.stringify(payload) : "";
243+
const useTextModule =
244+
state.isBuildMode &&
245+
preset === "cloudflare" &&
246+
override !== "0" &&
247+
(hasTrie || hasEntries) &&
248+
(override === "1" || payloadJson.length >= MANIFEST_EXTERNALIZE_THRESHOLD);
249+
250+
if (useTextModule) {
251+
const dir = join(state.projectRoot, "node_modules", ".rango");
252+
mkdirSync(dir, { recursive: true });
253+
const safeId = `${routerId.replace(/[^a-zA-Z0-9_-]/g, "_")}-${shortHash(routerId)}`;
254+
const filePath = join(dir, `manifest-${safeId}.txt`).replaceAll("\\", "/");
255+
writeFileSync(filePath, payloadJson);
256+
lines.push(`import __manifestJson from ${JSON.stringify(filePath)};`);
257+
lines.push(`const __manifestData = JSON.parse(__manifestJson);`);
258+
emitManifestExports(lines, hasTrie, hasEntries);
259+
return lines.join("\n");
260+
}
261+
262+
if (hasTrie) {
175263
lines.push(`export const trie = ${jsonParseExpression(trie)};`);
176264
}
177-
if (entries && entries.length > 0) {
265+
if (hasEntries) {
178266
lines.push(
179267
`export const precomputedEntries = ${jsonParseExpression(entries)};`,
180268
);
181269
}
182270
return lines.join("\n") || "";
183271
}
272+
273+
function manifestPayload(
274+
trie: unknown,
275+
hasTrie: boolean,
276+
entries: unknown,
277+
hasEntries: boolean,
278+
): Record<string, unknown> {
279+
const payload: Record<string, unknown> = {};
280+
if (hasTrie) payload.t = trie;
281+
if (hasEntries) payload.p = entries;
282+
return payload;
283+
}
284+
285+
function emitManifestExports(
286+
lines: string[],
287+
hasTrie: boolean,
288+
hasEntries: boolean,
289+
): void {
290+
if (hasTrie) lines.push(`export const trie = __manifestData.t;`);
291+
if (hasEntries)
292+
lines.push(`export const precomputedEntries = __manifestData.p;`);
293+
}
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
import fs from "node:fs";
2+
import path from "node:path";
3+
import { fileURLToPath } from "node:url";
4+
import { expect, test } from "@playwright/test";
5+
import { useFixture } from "./fixture";
6+
7+
const distAssets = path.join(
8+
path.dirname(fileURLToPath(import.meta.url)),
9+
"..",
10+
"dist",
11+
"rsc",
12+
"assets",
13+
);
14+
15+
/**
16+
* Cloudflare builds ship the route trie / precomputedEntries as a workerd
17+
* Text module (assets/manifest-<routerId>-*.txt) instead of a JSON.parse
18+
* string literal inside the lazy manifest chunk (issue #665). This suite
19+
* pins that the build actually emits and wires the text module — a silent
20+
* fallback to the inline literal would pass every functional test while
21+
* losing the cold-start win.
22+
*
23+
* The Text module is cloudflare-only (workerd has no filesystem, so it is the
24+
* only way to get bytes into an isolate without JS compilation; node/vercel
25+
* keep the inline literal). This app's manifest is below the 512KB threshold
26+
* that triggers the channel automatically, so the production webServer forces
27+
* it with RANGO_MANIFEST_TEXT=1 (see playwright.config.ts) — the whole
28+
* production suite then runs on the Text channel, and this test asserts the
29+
* artifact.
30+
*
31+
* Production-only by nature: dev serves the manifest through the virtual
32+
* module with the inline literal (the whole dev suite covers that path).
33+
*/
34+
test.describe("manifest text module (production)", () => {
35+
const f = useFixture({
36+
root: ".",
37+
mode: "build",
38+
});
39+
40+
test("routes match through the text-module manifest", async ({ request }) => {
41+
// Any successful match proves the worker loaded trie data from the text
42+
// module: production tries are authoritative, so a missing/broken text
43+
// module would 404 (or 500 on import failure), not fall back silently.
44+
const response = await request.get(f.url("/docs"));
45+
expect(response.status()).toBe(200);
46+
});
47+
48+
test("build emits the manifest text module and the chunk imports it", () => {
49+
const assets = fs.readdirSync(distAssets);
50+
const textModules = assets.filter(
51+
(a) => a.startsWith("manifest-") && a.endsWith(".txt"),
52+
);
53+
expect(textModules.length).toBeGreaterThanOrEqual(1);
54+
55+
// The payload is the real manifest data, not a stub: `t` is the route
56+
// trie (matched at runtime), `p` the precomputed entries.
57+
const raw = fs.readFileSync(path.join(distAssets, textModules[0]!), "utf8");
58+
const payload = JSON.parse(raw);
59+
expect(payload).toHaveProperty("t");
60+
61+
// The asset is raw, un-escaped JSON — never routed through JS minification,
62+
// so no \\" bloat. This is half the point of the Text module (the other
63+
// half being no JS compile); an inline literal would ship double-quoted.
64+
expect(raw.startsWith('{"t":')).toBe(true);
65+
expect(raw).not.toContain('\\"');
66+
67+
// Some rsc chunk must import the text module by its emitted filename —
68+
// an orphaned .txt asset would mean the build silently reverted to the
69+
// inline literal.
70+
const imported = assets
71+
.filter((a) => a.endsWith(".js"))
72+
.some((a) =>
73+
fs
74+
.readFileSync(path.join(distAssets, a), "utf8")
75+
.includes(textModules[0]!),
76+
);
77+
expect(imported).toBe(true);
78+
});
79+
});

‎tests/cloudflare-basic/playwright.config.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,17 @@ export default defineConfig({
4242
// Build first so dist/ is ready for production tests and deps_ssr is
4343
// populated before the dev server starts (wrangler's module runner does
4444
// not recover from ERR_OUTDATED_OPTIMIZED_DEP if the build runs later).
45+
//
46+
// RANGO_MANIFEST_TEXT=1 forces the route manifest through the workerd
47+
// Text-module channel (issue #665) even though this app's manifest is
48+
// below the size threshold that would trigger it automatically. That
49+
// makes the whole production suite dogfood the Text channel on real
50+
// workerd, and lets manifest-text-module.test.ts assert the artifact
51+
// deterministically. Dev is unaffected (the channel is build-only).
4552
command: `pnpm build && rm -rf node_modules/.vite && pnpm dev --port ${DEV_PORT}`,
4653
port: DEV_PORT,
4754
reuseExistingServer: true,
55+
env: { ...process.env, RANGO_MANIFEST_TEXT: "1" },
4856
},
4957
{
5058
// Shared preview server for all production tests. Started after the dev

0 commit comments

Comments
 (0)