tanstack-start

TanStack Start

Use this skill when the work touches TanStack Start or @tanstack/react-start.

Workflow

1. Identify the app's current Start shape before changing code:
   • Package versions for @tanstack/react-start, @tanstack/react-router, build plugins, React, and optional @tanstack/react-query.
   • Build tool: Vite or Rsbuild.
   • Start entrypoints: src/router.tsx, src/routes/__root.tsx, generated routeTree.gen.ts, optional src/start.ts, and optional custom src/server.ts.
   • Route files under src/routes, especially loaders, server.handlers, middleware, and auth boundaries.
2. Refresh current docs when the task depends on latest behavior, deployment adapters, security defaults, RC/experimental APIs, or a version mismatch. Start from source-map.md.
3. For new apps or routing/setup work, use setup-routing.md.
4. When adding, moving, or reviewing page/layout UI, hooks, or helpers under src/routes, follow route-colocation.md. Prefer folder + index.tsx for every page; keep route-only UI in -components / -hooks / -lib; put reusable feature code in src/modules/<feature>/.
5. For data loading, server functions, server routes, middleware, env boundaries, auth, and execution-model issues, use server-data.md.
6. For deployment, production modes, prerendering, ISR, SPA mode, selective SSR, custom server entrypoints, and verification, use deployment-production.md.

Implementation Judgment

• Treat TanStack Start as a full-stack React framework powered by TanStack Router. Keep Router conventions central: typed file routes, route loaders, route context, search params, and route invalidation.
• Prefer folder + index.tsx for every page route (avoid flat page leaves when colocation is needed). Colocate route-only modules with hyphen-prefixed folders (-components, -hooks, -lib, …). Put reusable feature code in src/modules/<feature>/ (reuse test). Never add unprefixed non-route files under src/routes — they become URLs. Details: route-colocation.md.
• TanStack Start remains a Release Candidate as of 2026-10-01: feature-complete with an API considered stable, but not bug-free before v1. npm latest is the current recommended line. React Server Components remain experimental. Verify the latest docs before depending on unstable or newly changed behavior.
• Use server functions for same-origin app RPC. Use server routes for public or external HTTP endpoints, webhooks, form posts, and API-style Response handling.
• Do not rely on route guards as the data security boundary. Authorize every server function and server route that touches private data.
• With TanStack Query, create the QueryClient inside getRouter() (never module scope), wire setupRouterSsrQueryIntegration, share queryOptions between loader and component, and await critical data with queryClient.query (Query 5.102+; ensureQueryData is deprecated).
• Remember that route loaders are isomorphic. Put secrets and server-only work behind server functions, server routes, server-only utilities, or .server.* modules.
• If the app defines src/start.ts, explicitly preserve or install CSRF middleware for server functions.
• Read server environment variables per request in edge runtimes. Use public prefixes only for intentionally client-exposed values.
• Keep generated route-tree files generated; do not hand-edit them unless the repo explicitly owns a generated snapshot workflow.

Verification

Prefer the repo's existing checks. For meaningful Start changes, include at least the relevant subset of:

• Typecheck/build, ensuring route tree generation runs.
• Unit or integration tests for loaders, server functions, server routes, and middleware.
• Browser smoke test for navigation, hydration, redirects, pending/error states, and forms.
• Deployment or adapter smoke test when changing hosting, env, SSR mode, prerendering, or server entrypoints.
• For releases, the production checklist in deployment-production.md: secret leak scan, direct endpoint authorization, two-account cache isolation, status codes, and rollback.