Skip to content

Commit 72bdf1e

Browse files
t3dotggclaude
andauthored
perf(web): pre-bundle startup chunks when a shared dev server starts (#22210)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent b7b53d4 commit 72bdf1e

4 files changed

Lines changed: 175 additions & 3 deletions

File tree

‎apps/web/src/bundledDev.test.ts‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import { createLogger, createServer } from "vite-plus";
1212
import { expect, it } from "vite-plus/test";
1313

1414
import { tailwindPlugins } from "../vite/tailwind";
15+
import { warmLazyEntries } from "../vite/warmBundledDev";
1516

1617
const execFile = NodeUtil.promisify(NodeChildProcess.execFile);
1718

@@ -222,3 +223,42 @@ it("hot updates Tailwind classes when a source file changes in bundled dev", asy
222223
await NodeFSP.rm(root, { recursive: true, force: true });
223224
}
224225
});
226+
227+
it("warms the wanted lazy chunk chain and nothing else", async () => {
228+
const root = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "t3-warm-"));
229+
let server: Awaited<ReturnType<typeof createServer>> | undefined;
230+
231+
try {
232+
await NodeFSP.mkdir(NodePath.join(root, "src"));
233+
await NodeFSP.writeFile(
234+
NodePath.join(root, "index.html"),
235+
'<html><body><script type="module" src="/src/bootstrap.ts"></script></body></html>',
236+
);
237+
await NodeFSP.writeFile(NodePath.join(root, "src/bootstrap.ts"), 'void import("./main");');
238+
await NodeFSP.writeFile(
239+
NodePath.join(root, "src/main.ts"),
240+
'export const route = () => import("./route"); export const rare = () => import("./rare");',
241+
);
242+
await NodeFSP.writeFile(NodePath.join(root, "src/route.ts"), "export const route = 1;");
243+
await NodeFSP.writeFile(NodePath.join(root, "src/rare.ts"), "export const rare = 1;");
244+
245+
server = await createServer({
246+
configFile: false,
247+
root,
248+
logLevel: "silent",
249+
experimental: { bundledDev: true },
250+
server: { host: "127.0.0.1", port: 0 },
251+
});
252+
await server.listen();
253+
254+
// The route is only discoverable after main compiles, so this also covers the pass walk.
255+
const warmed = await warmLazyEntries(server, ["src/main.ts", "src/route.ts"]);
256+
expect(warmed.map((id) => NodePath.relative(root, id.split("?")[0] ?? id))).toEqual([
257+
"src/main.ts",
258+
"src/route.ts",
259+
]);
260+
} finally {
261+
await server?.close();
262+
await NodeFSP.rm(root, { recursive: true, force: true });
263+
}
264+
});

‎apps/web/vite.config.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import {
1818
import { loadRepoEnv } from "../../scripts/lib/public-config";
1919
import { thirdPartyLicensesPlugin } from "../../scripts/lib/third-party-licenses";
2020
import { tailwindPlugins } from "./vite/tailwind";
21+
import { warmBundledDevPlugin } from "./vite/warmBundledDev";
2122

2223
const repoEnv = loadRepoEnv();
2324
Object.assign(process.env, repoEnv);
@@ -186,6 +187,7 @@ export default defineConfig(() => {
186187
tanstackRouter({ autoCodeSplitting: true }),
187188
react({ compiler: true }),
188189
tailwindPlugins(bundledDev),
190+
warmBundledDevPlugin(),
189191
],
190192
optimizeDeps: {
191193
include: [
@@ -239,7 +241,8 @@ export default defineConfig(() => {
239241
// Transform the whole module graph at server start instead of on the
240242
// first request. Without this, a cold worktree discovers and transforms
241243
// modules one import-level at a time while the browser waits — which
242-
// over a tailnet origin turns into minutes of waterfall.
244+
// over a tailnet origin turns into minutes of waterfall. Bundled dev
245+
// ignores this; warmBundledDevPlugin covers it there.
243246
warmup: {
244247
clientFiles: ["./src/main.tsx"],
245248
},

‎apps/web/vite/warmBundledDev.ts‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
import type { Plugin, ViteDevServer } from "vite-plus";
2+
3+
// What the first page load pulls in: the app, the managed-auth shell, the chat
4+
// layout and its landing routes, and the sidebar's project icons.
5+
const STARTUP_LAZY_ENTRIES = [
6+
"src/main.tsx",
7+
"src/components/clerk/BrowserManagedAuthShell.tsx",
8+
"src/routes/_chat.tsx",
9+
"src/routes/_chat.index.tsx",
10+
"src/routes/_chat.$environmentId.$threadId.tsx",
11+
"src/lib/lucideIconByName.ts",
12+
];
13+
14+
const WARMUP_CLIENT_ID = "t3code-startup-warmup";
15+
16+
// Bundled dev keeps these private and untyped. A Vite upgrade that moves them
17+
// skips the warmup or logs a warning, never breaks dev; bundledDev.test.ts
18+
// fails so the upgrade cannot drop the warmup silently.
19+
interface BundledDevInternals {
20+
waitForInitialBuildFinish(): Promise<void>;
21+
triggerLazyBundling(
22+
moduleId: string,
23+
clientId: string,
24+
): Promise<{ readonly filename: string } | undefined>;
25+
markPayloadDelivered(filename: string): void;
26+
readonly devEngine: {
27+
readonly moduleGraph: {
28+
getModuleIds(): readonly string[];
29+
getModuleInfo(id: string): { readonly dynamicallyImportedIds: readonly string[] } | null;
30+
};
31+
removeClient(clientId: string): Promise<void>;
32+
};
33+
}
34+
35+
function hasBundledDevInternals(value: unknown): value is BundledDevInternals {
36+
return (
37+
typeof value === "object" &&
38+
value !== null &&
39+
"waitForInitialBuildFinish" in value &&
40+
typeof value.waitForInitialBuildFinish === "function" &&
41+
"triggerLazyBundling" in value &&
42+
typeof value.triggerLazyBundling === "function" &&
43+
"markPayloadDelivered" in value &&
44+
typeof value.markPayloadDelivered === "function"
45+
);
46+
}
47+
48+
/**
49+
* Compiles `entries` as lazy chunks once, for a throwaway client, and returns
50+
* the lazy module ids it compiled. The browser's own requests then reuse
51+
* Rolldown's transform cache. Entries are paths relative to the Vite root.
52+
*/
53+
export async function warmLazyEntries(
54+
server: ViteDevServer,
55+
entries: readonly string[],
56+
): Promise<string[]> {
57+
// Widened so the guard narrows to the internals, not to Vite's public class.
58+
const bundledDev: unknown = server.environments.client.bundledDev;
59+
if (!hasBundledDevInternals(bundledDev)) return [];
60+
await bundledDev.waitForInitialBuildFinish();
61+
62+
const { moduleGraph } = bundledDev.devEngine;
63+
// Vite's root and Rolldown's module ids are both absolute, slash-separated paths.
64+
const wanted = new Set(entries.map((entry) => `${server.config.root}/${entry}`));
65+
const warmed = new Set<string>();
66+
// A lazy entry is only in the graph after its parent compiled, so walk in
67+
// passes. Each pass compiles at least one new wanted id, so it ends.
68+
const nextLazyIds = () =>
69+
new Set(
70+
moduleGraph
71+
.getModuleIds()
72+
.flatMap((id) => moduleGraph.getModuleInfo(id)?.dynamicallyImportedIds ?? [])
73+
.filter(
74+
(id) =>
75+
id.includes("rolldown-lazy") && !warmed.has(id) && wanted.has(id.split("?")[0] ?? id),
76+
),
77+
);
78+
79+
try {
80+
for (let pending = nextLazyIds(); pending.size > 0; pending = nextLazyIds()) {
81+
for (const id of pending) {
82+
warmed.add(id);
83+
const result = await bundledDev.triggerLazyBundling(id, WARMUP_CLIENT_ID);
84+
// Acked so the engine drops the pending payload instead of holding the chunk.
85+
if (result) bundledDev.markPayloadDelivered(result.filename);
86+
}
87+
}
88+
} finally {
89+
await bundledDev.devEngine.removeClient(WARMUP_CLIENT_ID);
90+
}
91+
return [...warmed];
92+
}
93+
94+
// Bundled dev builds only the small bootstrap entry at startup. The app and its
95+
// routes are lazy chunks, compiled on first request, one import level at a
96+
// time. Cold, that chain costs ~25s of serial compile before first paint
97+
// (`server.warmup` does nothing in bundled dev). Warming it as soon as the
98+
// server listens leaves the browser mostly codegen.
99+
export function warmBundledDevPlugin(): Plugin {
100+
return {
101+
name: "t3code:warm-bundled-dev",
102+
apply: "serve",
103+
configureServer(server) {
104+
if (!server.config.experimental.bundledDev) return;
105+
server.httpServer?.once("listening", () => {
106+
const startedAt = performance.now();
107+
warmLazyEntries(server, STARTUP_LAZY_ENTRIES).then(
108+
(warmed) => {
109+
if (warmed.length === 0) return;
110+
const seconds = ((performance.now() - startedAt) / 1000).toFixed(1);
111+
server.config.logger.info(
112+
`[t3code] pre-bundled ${String(warmed.length)} startup chunks in ${seconds}s`,
113+
{ timestamp: true },
114+
);
115+
},
116+
(error: unknown) => {
117+
server.config.logger.warn(`[t3code] startup chunk warmup failed: ${String(error)}`, {
118+
timestamp: true,
119+
});
120+
},
121+
);
122+
});
123+
},
124+
};
125+
}

‎docs/operations/development.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,9 +52,13 @@ when changing this setup:
5252
chunks. Static imports can work on first load and fail after a route split.
5353
- Bundled dev rebuilds Tailwind through watched files. Its ordinary Vite hot-update hook expects
5454
a server/module graph that Rolldown does not provide.
55+
- The app and its routes are lazy chunks, built on first request. A plugin pre-bundles the
56+
startup chain when the server starts. Renaming or moving a startup route or the app entry
57+
silently drops it from that list.
5558

56-
The workarounds live in the [web entry](../../apps/web/src/bootstrap.ts) and
57-
[Tailwind plugin](../../apps/web/vite/tailwind.ts).
59+
The workarounds live in the [web entry](../../apps/web/src/bootstrap.ts),
60+
[Tailwind plugin](../../apps/web/vite/tailwind.ts), and
61+
[startup warmup](../../apps/web/vite/warmBundledDev.ts).
5862

5963
#### Reusable dev credential
6064

0 commit comments

Comments
 (0)