Skip to content

Commit ee7eb9c

Browse files
committed
perf(vite): ship route-manifest data through a runtime channel on both node and workerd (refs #665)
At route scale the per-router manifest chunk inlined trie + precomputedEntries as JSON.parse('<literal>'). The isolate's/process's first request pays for it twice: V8 lexes+compiles the multi-MB source literal, then JSON.parse runs. Shipping the JSON through a runtime channel skips the compile pass. The compile cost is a V8 property, not platform-specific, so both runtimes benefit — measured cold at 26k routes: ~13.6ms saved on Node (Node 24, M4; 37.8ms -> 24.2ms isolated manifest load) and ~17% median cold first-hit on the Cloudflare edge. Two delivery channels, because the runtimes expose bundle-adjacent bytes differently: - cloudflare/workerd: no filesystem — a Text module import is the only way to get raw bytes into an isolate without JS compilation. The CF plugin types .txt imports as Text; the staging file is written during load(). (preset: cloudflare) - node/vercel: no Text module type, but a real filesystem — emit the JSON as a Rollup asset (this.emitFile) and read it at runtime with fs.readFileSync via the asset's hashed URL (import.meta.ROLLUP_FILE_URL). The vercel preset copies dist/rsc wholesale into the .func dir, so the asset is co-located and the relative reference resolves. (preset: node | vercel) Both feed the same JSON.parse -> exports, so ensureRouterManifest() and the trie consumer are identical across channels. Chosen by state.preset. Build mode only (dev keeps the inline literal — the manifest is rebuilt on every HMR and parse cost is irrelevant). Below a 32KB serialized- payload threshold the inline literal wins (its compile is sub-ms, less than the fs read it would replace), so small apps stay byte-identical. RANGO_MANIFEST_TEXT=0/1 overrides the gate and threshold for A/B and tests. Bundle hygiene preserved: data still lives in exactly one lazy artifact per router, and an asset/Text module can't be duplicated into an eager chunk by Rollup. Coverage: unit tests over the full gate matrix (both channels, threshold boundary, dev fallback, overrides, id sanitization); node-preset production e2e (test-app: routes resolve through the fs-loaded trie + asset emitted and read via fs); cloudflare-preset production e2e (cloudflare-basic, forced via RANGO_MANIFEST_TEXT=1 as its manifest is below threshold — whole prod suite then dogfoods the Text channel on real workerd); vercel output assembly verified to co-locate the asset. bench/{cold-only,edge-cold}.ts A/B harnesses + a Node cold microbench.
1 parent 99f052b commit ee7eb9c

8 files changed

Lines changed: 541 additions & 3 deletions

File tree

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
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+
"test-app",
10+
"dist",
11+
"rsc",
12+
"assets",
13+
);
14+
15+
/**
16+
* On the node/vercel preset the route trie / precomputedEntries ship as a
17+
* Rollup JSON asset read at runtime with fs.readFileSync, instead of a
18+
* JSON.parse string literal compiled into the chunk (issue #665). The
19+
* mechanism is the Node counterpart of the Cloudflare Text module: same
20+
* data, different delivery channel, chosen because Node has a filesystem but
21+
* no workerd Text module type. This suite pins that test-app's build (its
22+
* manifest clears the externalize threshold) emits and wires the asset, and
23+
* that routes still resolve through the fs-loaded trie at runtime.
24+
*
25+
* Production-only by nature: dev serves the manifest inline through the
26+
* virtual module (the whole dev suite covers that path).
27+
*/
28+
test.describe("manifest fs channel — node preset (production)", () => {
29+
const f = useFixture({
30+
root: "./e2e/test-app",
31+
mode: "build",
32+
});
33+
34+
test("routes resolve through the fs-loaded manifest", async ({ request }) => {
35+
// The production trie is authoritative: a miss is a direct 404, never a
36+
// fallback. A successful match on a real nested route proves the worker
37+
// loaded trie data from the fs asset, not from a silent inline fallback.
38+
for (const p of ["/loading-fn-test", "/__test/loader-ids"]) {
39+
const res = await request.get(f.url(p));
40+
expect(res.status(), `${p} should resolve`).toBe(200);
41+
}
42+
});
43+
44+
test("build emits the manifest json asset and a chunk reads it via fs", () => {
45+
const assets = fs.readdirSync(distAssets);
46+
const jsonAssets = assets.filter(
47+
(a) => a.startsWith("manifest-") && a.endsWith(".json"),
48+
);
49+
expect(jsonAssets.length).toBeGreaterThanOrEqual(1);
50+
51+
const payload = JSON.parse(
52+
fs.readFileSync(path.join(distAssets, jsonAssets[0]!), "utf8"),
53+
);
54+
expect(payload).toHaveProperty("t");
55+
56+
// Some chunk must reference the emitted asset by name AND read it with
57+
// fs — an orphaned asset would mean the build silently reverted to the
58+
// inline literal.
59+
const chunk = assets
60+
.filter((a) => a.endsWith(".js"))
61+
.map((a) => fs.readFileSync(path.join(distAssets, a), "utf8"))
62+
.find((src) => src.includes(jsonAssets[0]!));
63+
expect(chunk, "a chunk imports the manifest asset").toBeTruthy();
64+
expect(chunk).toContain("readFileSync");
65+
});
66+
});
Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
import { describe, it, expect, beforeEach, afterEach } from "vitest";
2+
import { mkdtempSync, readFileSync, existsSync, rmSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join } from "node:path";
5+
import { generatePerRouterModule } from "../virtual-module-codegen";
6+
import { createDiscoveryState, type DiscoveryState } from "../state";
7+
8+
// A trie whose serialized form clears MANIFEST_EXTERNALIZE_THRESHOLD (32KB):
9+
// 800 static leaves at ~50 bytes each. Below-threshold variant uses a handful.
10+
function bigTrie(n: number) {
11+
const s: Record<string, unknown> = {};
12+
for (let i = 0; i < n; i++) {
13+
s[`route-segment-number-${i}`] = {
14+
r: { n: `route.name.number.${i}`, sp: "", a: ["M0L0", `M0L0R${i}`] },
15+
};
16+
}
17+
return { s };
18+
}
19+
const BIG = bigTrie(800);
20+
const SMALL = bigTrie(3);
21+
const ENTRIES = [{ staticPrefix: "", routes: { home: "/" } }];
22+
23+
let tmpRoot: string;
24+
let savedOverride: string | undefined;
25+
26+
beforeEach(() => {
27+
tmpRoot = mkdtempSync(join(tmpdir(), "rango-vmc-"));
28+
savedOverride = process.env.RANGO_MANIFEST_TEXT;
29+
delete process.env.RANGO_MANIFEST_TEXT;
30+
});
31+
32+
afterEach(() => {
33+
rmSync(tmpRoot, { recursive: true, force: true });
34+
if (savedOverride === undefined) delete process.env.RANGO_MANIFEST_TEXT;
35+
else process.env.RANGO_MANIFEST_TEXT = savedOverride;
36+
});
37+
38+
function makeState(
39+
preset: "node" | "cloudflare" | "vercel",
40+
opts: { isBuildMode?: boolean; trie?: unknown } = {},
41+
routerId = "r1",
42+
): DiscoveryState {
43+
const s = createDiscoveryState(undefined, { preset });
44+
s.projectRoot = tmpRoot;
45+
s.isBuildMode = opts.isBuildMode ?? true;
46+
s.perRouterManifests.push({ id: routerId, routeManifest: { home: "/" } });
47+
s.perRouterManifestDataMap.set(routerId, { home: "/" });
48+
s.perRouterTrieMap.set(routerId, opts.trie ?? BIG);
49+
s.perRouterPrecomputedMap.set(routerId, ENTRIES);
50+
return s;
51+
}
52+
53+
// Records emitFile calls and hands back a fake Rollup reference id.
54+
function makeEmitAsset() {
55+
const calls: Array<{ fileName: string; source: string }> = [];
56+
const fn = (fileName: string, source: string): string => {
57+
calls.push({ fileName, source });
58+
return "abc123";
59+
};
60+
return Object.assign(fn, { calls });
61+
}
62+
63+
const stagedTxt = (root: string, routerId: string) =>
64+
join(root, "node_modules", ".rango", `manifest-${routerId}.txt`);
65+
66+
describe("generatePerRouterModule — cloudflare Text channel", () => {
67+
it("emits a .txt import and stages the JSON payload above threshold", () => {
68+
const s = makeState("cloudflare");
69+
const code = generatePerRouterModule(s, "r1", makeEmitAsset());
70+
71+
expect(code).toContain("import __manifestJson from");
72+
expect(code).toContain(".txt");
73+
expect(code).toContain("export const trie = __manifestData.t;");
74+
expect(code).toContain(
75+
"export const precomputedEntries = __manifestData.p;",
76+
);
77+
expect(code).not.toContain("export const trie = JSON.parse(");
78+
79+
const staged = stagedTxt(tmpRoot, "r1");
80+
expect(existsSync(staged)).toBe(true);
81+
expect(JSON.parse(readFileSync(staged, "utf8"))).toEqual({
82+
t: BIG,
83+
p: ENTRIES,
84+
});
85+
});
86+
87+
it("does not use the Node fs channel even when emitAsset is available", () => {
88+
const emit = makeEmitAsset();
89+
const code = generatePerRouterModule(makeState("cloudflare"), "r1", emit);
90+
expect(code).not.toContain("readFileSync");
91+
expect(emit.calls).toHaveLength(0);
92+
});
93+
});
94+
95+
describe("generatePerRouterModule — node/vercel fs channel", () => {
96+
for (const preset of ["node", "vercel"] as const) {
97+
it(`${preset}: emits an asset and reads it via fs at runtime`, () => {
98+
const emit = makeEmitAsset();
99+
const code = generatePerRouterModule(makeState(preset), "r1", emit);
100+
101+
expect(code).toContain('readFileSync as __readFileSync } from "node:fs"');
102+
expect(code).toContain("import.meta.ROLLUP_FILE_URL_abc123");
103+
expect(code).toContain("export const trie = __manifestData.t;");
104+
expect(code).not.toContain("export const trie = JSON.parse(");
105+
106+
expect(emit.calls).toHaveLength(1);
107+
expect(emit.calls[0]!.fileName).toBe("manifest-r1.json");
108+
expect(JSON.parse(emit.calls[0]!.source)).toEqual({ t: BIG, p: ENTRIES });
109+
// No workerd staging file on the Node channel.
110+
expect(existsSync(stagedTxt(tmpRoot, "r1"))).toBe(false);
111+
});
112+
}
113+
114+
it("node: falls back to the inline literal when emitAsset is unavailable", () => {
115+
// e.g. dev, or a non-build context — no Rollup emitFile to call.
116+
const code = generatePerRouterModule(makeState("node"), "r1", undefined);
117+
expect(code).toContain("export const trie = JSON.parse(");
118+
expect(code).not.toContain("readFileSync");
119+
});
120+
});
121+
122+
describe("generatePerRouterModule — gating", () => {
123+
it("dev keeps the inline literal on every preset", () => {
124+
for (const preset of ["node", "cloudflare", "vercel"] as const) {
125+
const code = generatePerRouterModule(
126+
makeState(preset, { isBuildMode: false }),
127+
"r1",
128+
makeEmitAsset(),
129+
);
130+
expect(code).toContain("export const trie = JSON.parse(");
131+
expect(code).not.toContain(".txt");
132+
expect(code).not.toContain("readFileSync");
133+
}
134+
});
135+
136+
it("below the size threshold keeps the inline literal", () => {
137+
const cf = generatePerRouterModule(
138+
makeState("cloudflare", { trie: SMALL }),
139+
"r1",
140+
makeEmitAsset(),
141+
);
142+
expect(cf).toContain("export const trie = JSON.parse(");
143+
const node = generatePerRouterModule(
144+
makeState("node", { trie: SMALL }),
145+
"r1",
146+
makeEmitAsset(),
147+
);
148+
expect(node).toContain("export const trie = JSON.parse(");
149+
expect(node).not.toContain("readFileSync");
150+
});
151+
152+
it("RANGO_MANIFEST_TEXT=1 externalizes below the threshold", () => {
153+
process.env.RANGO_MANIFEST_TEXT = "1";
154+
const emit = makeEmitAsset();
155+
const code = generatePerRouterModule(
156+
makeState("node", { trie: SMALL }),
157+
"r1",
158+
emit,
159+
);
160+
expect(code).toContain("readFileSync");
161+
expect(emit.calls).toHaveLength(1);
162+
});
163+
164+
it("RANGO_MANIFEST_TEXT=0 forces the inline literal above the threshold", () => {
165+
process.env.RANGO_MANIFEST_TEXT = "0";
166+
const emit = makeEmitAsset();
167+
const code = generatePerRouterModule(makeState("cloudflare"), "r1", emit);
168+
expect(code).toContain("export const trie = JSON.parse(");
169+
expect(code).not.toContain(".txt");
170+
expect(emit.calls).toHaveLength(0);
171+
});
172+
173+
it("sanitizes router ids in staged/emitted file names", () => {
174+
const cf = generatePerRouterModule(
175+
makeState("cloudflare", {}, "a/b.c"),
176+
"a/b.c",
177+
);
178+
expect(cf).toContain("manifest-a_b_c.txt");
179+
expect(existsSync(stagedTxt(tmpRoot, "a_b_c"))).toBe(true);
180+
181+
const emit = makeEmitAsset();
182+
generatePerRouterModule(makeState("node", {}, "a/b.c"), "a/b.c", emit);
183+
expect(emit.calls[0]!.fileName).toBe("manifest-a_b_c.json");
184+
});
185+
});

0 commit comments

Comments
 (0)