The best way to control Claude Code, Codex and more from any computer or phone
perf(web): pre-bundle startup chunks when a shared dev server starts (#22210)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 20, 2026 at 01:14 UTC
72bdf1e658c6f875534b870fa02e38c5648ccec3
4 files changed
+175
-3
apps/web/src/bundledDev.test.ts
+40
@@ -12,6 +12,7 @@ import { createLogger, createServer } from "vite-plus";
12
import { expect, it } from "vite-plus/test";
13
14
import { tailwindPlugins } from "../vite/tailwind";
15
+import { warmLazyEntries } from "../vite/warmBundledDev";
16
17
const execFile = NodeUtil.promisify(NodeChildProcess.execFile);
18
@@ -222,3 +223,42 @@ it("hot updates Tailwind classes when a source file changes in bundled dev", asy
223
await NodeFSP.rm(root, { recursive: true, force: true });
224
}
225
});
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
+4
-1
@@ -18,6 +18,7 @@ import {
18
import { loadRepoEnv } from "../../scripts/lib/public-config";
19
import { thirdPartyLicensesPlugin } from "../../scripts/lib/third-party-licenses";
20
import { tailwindPlugins } from "./vite/tailwind";
21
+import { warmBundledDevPlugin } from "./vite/warmBundledDev";
22
23
const repoEnv = loadRepoEnv();
24
Object.assign(process.env, repoEnv);
@@ -186,6 +187,7 @@ export default defineConfig(() => {
187
tanstackRouter({ autoCodeSplitting: true }),
188
react({ compiler: true }),
189
tailwindPlugins(bundledDev),
190
+ warmBundledDevPlugin(),
191
],
192
optimizeDeps: {
193
include: [
@@ -239,7 +241,8 @@ export default defineConfig(() => {
241
// Transform the whole module graph at server start instead of on the
242
// first request. Without this, a cold worktree discovers and transforms
243
// 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.
246
warmup: {
247
clientFiles: ["./src/main.tsx"],
248
},
apps/web/vite/warmBundledDev.ts
new
+125
@@ -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
+6
-2
@@ -52,9 +52,13 @@ when changing this setup:
52
chunks. Static imports can work on first load and fail after a route split.
53
- Bundled dev rebuilds Tailwind through watched files. Its ordinary Vite hot-update hook expects
54
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.
58
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).
62
63
#### Reusable dev credential
64