perf(web): halve the cold-start bundle by splitting Clerk and cold routes

[StiensWout]

Every web and desktop client downloads ~2.15 MB gzip of JavaScript before first paint, and ~565 KB of that is the bundled clerk-js runtime that local-mode users never run: the entry statically imports the Electron Clerk provider (which bundles clerk-js) even in the browser, where Clerk hotloads its runtime from CDN anyway. The generated route tree also eagerly pulls settings, pull-request, and usage code into the entry, and the root route pins the theme editor and settings sidebar nav there too.

This splits the cold-start graph along its existing runtime conditionals:

• Managed auth lazy-loads only the selected Clerk runtime (browser or Electron shell) behind the existing clerkPublishableKey && hasCloudPublicConfig() gate. Local mode downloads no Clerk at all; the browser build no longer bundles clerk-js.
• Route components become split chunks (autoCodeSplitting on the TanStack Router plugin), prefetched on navigation intent (defaultPreload: "intent") so first settings/PR navigation does not pay the load.
• The theme editor panel and settings sidebar nav lazy-load behind their existing "only renders when active" conditions, since the root route keeps them out of route splitting's reach.

Measured on a production build (gzip -6, entry + modulepreloads + CSS from index.html): 2.15 MB → 0.89 MB (−59%). The Electron Clerk runtime is now a 555 KB chunk loaded only in the desktop shell with cloud config; only the small @clerk/react/@clerk/shared hook layer (~86 KB) remains entry-resident for always-mounted consumers. Desktop chunk loading goes through the existing t3code:// protocol proxy, which forwards arbitrary /assets/* paths, so split chunks resolve the same way the entry does.

Verified with the web unit tests around the touched areas (routes titlebar, Clerk profile pages, Electron passkeys, managed auth, AppRoot), targeted lint, and a web typecheck, plus the before/after bundle measurement above.

---

Change authored by Claude Fable 5 running in Claude Code.

🤖 Generated with Claude Code

---

Note

Medium Risk
Startup and auth wiring changed (deferred render, lazy Clerk shells, chunk-load reload), so regressions could affect first paint, cloud login, or behavior after deploys—though local mode and error paths are explicitly handled.

Overview
Cuts cold-start JavaScript by splitting the entry graph (~2.15 MB gzip → ~0.89 MB in the PR’s measurement) by moving Clerk, route pages, and a few always-mounted-but-rarely-used UI behind lazy chunks instead of static imports.

Managed auth no longer loads at startup: main.tsx dynamically imports BrowserManagedAuthShell or ElectronManagedAuthShell only when cloud config and a Clerk publishable key are present, so local mode skips Clerk entirely and the browser build avoids bundling the Electron clerk-js payload on the critical path.

Route code is code-split via TanStack Router autoCodeSplitting in Vite, with defaultPreload: "intent" so settings/PR-style routes prefetch on hover/focus rather than on first paint. Settings sidebar nav and theme editor panel are React.lazy + Suspense where they only mount when settings or an editor session is active.

Boot behavior changes: first paint waits on router.load() and the optional auth shell chunk so the HTML boot splash stays visible until real UI can render; vite:preloadError triggers a one-shot reload (chunkReloadGuard) when stale hashed assets 404 after deploy, with tests for the guard.

^{Reviewed by Cursor Bugbot for commit 0bbaa39. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Split Clerk and cold routes to halve web cold-start bundle

• Moves Clerk browser and Electron provider implementations into separate dynamically loaded auth-shell modules; startup loads only the one selected by the environment, or neither when cloud config is absent
• Enables TanStack Router automatic route code splitting in vite.config.ts and configures the router to preload route chunks on hover/focus intent
• Lazily loads the settings navigation in AppSidebarLayout.tsx and the theme editor panel in ThemeEditorHost.tsx, each wrapped in a Suspense boundary with an empty fallback
• Adds a chunk-reload guard in chunkReloadGuard.ts that reloads once on the first split-chunk load failure using a session-storage marker, and surfaces subsequent failures without reloading
• Startup in main.tsx now awaits the selected auth shell and router before the first React render, and writes a load-failure message to the boot shell if startup rejects without a scheduled reload
• Risk: if a user's session storage is blocked, the chunk-reload guard will not attempt a reload and the raw chunk-load error surfaces to the boot shell instead

^{Macroscope summarized 0bbaa39.}

[macroscopeapp]

One finding: the new top-level Suspense boundary makes the first React commit paint nothing, which tears down the index.html boot splash on cloud cold starts. Details inline on apps/web/src/main.tsx.

^{Posted via Macroscope — UI Consistency}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 308df80. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This change substantially rewires production startup and authentication loading across browser and Electron clients, while also adding global route-splitting and chunk-recovery behavior. The modified authentication directory and cross-cutting first-paint/error-path changes warrant focused human review.

^{You can add or adjust custom eligibility rules. Learn more.}