TanStack Start Optimizer

Audit a TanStack Start codebase, report what is slow or fragile and why, agree a plan with the user, then fix it. Order: evidence, approval, edits. Start's performance model is route loaders plus selective SSR, and its security model is server functions as public endpoints; changing either silently changes correctness, so nothing is edited before approval.

Workflow

1. Scope (quick)

• Find the root (package.json with @tanstack/react-start). Record: Start version, TanStack Router version, build tool (Vite 8+/Rsbuild), React 18/19, Node runtime (Start requires >=22.12), rendering mode (SSR by default, selective ssr, SPA, prerender), TanStack Query integration, and deployment target (Nitro/Cloudflare/Netlify/Node).
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json, vite.config.*, src/start.ts, src/router.tsx, root/route files and server functions for legacy Vinxi, loader leakage, cache/preload defaults, server-function validation/CSRF, code-splitting blockers and bundle risks, with file:line evidence. Use --json to post-process.
• Classify the pain: slow initial load (SSR/bundle), slow navigation (loaders/cache), slow mutations (server functions), hydration/CLS, deployment cold start, or code health/security. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here (production build, router devtools, bundle analyzer, server timing, load tests).

2. Audit

The script finds cheap leads; you find the rest by reading. Read package.json, vite.config.*, src/router.tsx, src/routes/__root.tsx, the 3-5 routes the user cares about, and the server functions they call. Load only what applies:

Measure, never guess. Build and run the production start command (Nitro/Node output, vite preview for plugin-based hosts, or the Cloudflare preview), then measure that. Record route-level JS, loader timing, SSR TTFB, hydration cost and LCP/INP/CLS. Dev mode and the Vite dev server are not evidence.

Mark each finding Confirmed (build output, network/profiler, code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as TANSTACK_START_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, behavior impact). Group near-duplicates.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- defaultPreload: 'intent', per-route staleTime, remove fetch-in-effect, parallelize independent loader calls, set body/cache headers, lazy-load heavy widgets, delete dead route exports. Low risk.
2. Structural -- move data into loaders/server functions, batch N+1 calls with loaderDeps, split slow routes, choose ssr: 'data-only'/false where justified, adopt Query integration with a per-router client, validate search/server input. Name each behavior change.
3. Heavy -- Vinxi/beta to Vite 8 Start 1.x, Rsbuild adoption, SPA/prerender migration, server-function architecture, framework/RSC adoption. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: tsc --noEmit, lint, tests, vite build (or rsbuild build), then start the production server. A break must trace to one change. Do not mix a Start/Router/Vite major upgrade with optimization edits. If an approved change moves an auth check out of a server function, exposes server-only code to the client, or changes SSR output, stop and ask.

6. Verify and wrap up

Re-measure the same routes and scenario: route JS (raw/gzip), SSR TTFB, loader duration, navigation time, LCP/INP/CLS, and server-function latency. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Loaders are the data boundary. Fetch in a loader (or server function), not in useEffect; component fetching creates waterfalls and layout shift.
• Loaders are isomorphic. They run on the server for the first request and in the browser on navigation; database, filesystem and secrets belong in createServerFn.
• Server functions are public endpoints. Enforce auth inside the handler or middleware; route beforeLoad is UX, not a security boundary.
• Validate every boundary. Search params, server-function input and server-route bodies all cross the network; use Zod/Standard Schema.
• Cache deliberately. Router staleTime defaults to 0 and preload data is fresh for 30s, retained for 5 minutes; set per-route freshness and loaderDeps, and invalidate after mutations.
• SSR is per-route. Full SSR by default; data-only for browser-only markup, false for client-only screens, SPA/prerender only with a reason.
• Code splitting is on, but exports defeat it. Do not export route components/options; check actual chunks, not the config.
• One QueryClient per router. A module-scope client leaks one user's cache into another user's SSR HTML.
• Docs move. Start v1 (Oct 2026) uses Vite 8, validator() and build plugins; Vinxi-era advice is stale. Check the installed version.