start-core

1---2name: start-core3description: >-4  Core overview for TanStack Start: tanstackStart() Vite plugin,5  getRouter() factory, root route document shell (HeadContent,6  Scripts, Outlet), client/server entry points, routeTree.gen.ts,7  tsconfig configuration. Entry point for all Start skills.8metadata:9  type: core10  library: tanstack-start11  library_version: '1.170.14'12sources:13  - TanStack/router:docs/start/framework/react/build-from-scratch.md14  - TanStack/router:docs/start/framework/react/quick-start.md15  - TanStack/router:docs/start/framework/react/guide/routing.md16---17 18# TanStack Start Core19 20TanStack Start is a full-stack React framework built on TanStack Router and Vite. It adds SSR, streaming, server functions (type-safe RPCs), middleware, server routes, and universal deployment.21 22> **CRITICAL**: All code in TanStack Start is ISOMORPHIC by default — it runs in BOTH server and client environments. Loaders run on both server AND client. To run code exclusively on the server, use `createServerFn`. This is the #1 AI agent mistake.23> **CRITICAL**: TanStack Start is NOT Next.js. Do not generate `getServerSideProps`, `"use server"` directives, `app/layout.tsx`, or any Next.js/Remix patterns. Use `createServerFn` for server-only code.24> **CRITICAL**: Types are FULLY INFERRED. Never cast, never annotate inferred values.25 26Use this entry skill to pick one primary workflow. Do not load every Start sub-skill. Add another only when the implementation crosses that boundary; for example, a protected mutation needs `server-functions` plus `auth-server-primitives`, while a public REST endpoint needs `server-routes` alone.27 28## Sub-Skills29 30| Task                                             | Sub-Skill                                                                       |31| ------------------------------------------------ | ------------------------------------------------------------------------------- |32| Type-safe RPCs, data fetching, mutations         | [start-core/server-functions/SKILL.md](./server-functions/SKILL.md)             |33| Request/function middleware, context, auth       | [start-core/middleware/SKILL.md](./middleware/SKILL.md)                         |34| Server-side auth: sessions, cookies, OAuth, CSRF | [start-core/auth-server-primitives/SKILL.md](./auth-server-primitives/SKILL.md) |35| Isomorphic execution, environment boundaries     | [start-core/execution-model/SKILL.md](./execution-model/SKILL.md)               |36| REST API endpoints alongside app routes          | [start-core/server-routes/SKILL.md](./server-routes/SKILL.md)                   |37| Hosting, SSR modes, prerendering, SEO            | [start-core/deployment/SKILL.md](./deployment/SKILL.md)                         |38 39## Quick Decision Tree40 41```text42Need to run code exclusively on the server (DB, secrets)?43  → start-core/server-functions44 45Need auth checks, logging, or shared logic across server functions?46  → start-core/middleware47 48Need to add login, sessions, OAuth, CSRF, password reset?49  → start-core/auth-server-primitives50 51Need to understand where code runs (server vs client)?52  → start-core/execution-model53 54Need a REST API endpoint (GET/POST/PUT/DELETE)?55  → start-core/server-routes56 57Need to deploy, configure SSR, or prerender?58  → start-core/deployment59```60 61## Full-Stack Delivery Workflow62 63For application data loaded by a Start route:64 651. Put database, filesystem, secrets, and persistence code behind `createServerFn`.662. Call the server function directly from the route loader. Do not self-fetch a relative `/api/...` URL from an SSR loader.673. Validate every input and enforce auth in the server function or middleware. `beforeLoad` only protects route UX.684. After a mutation resolves, invalidate the router or the external query cache and await the refresh when the UI must be current before continuing.695. For schema changes, update storage, validation, handler serialization, loader, and UI. Assert the actual runtime payload; typechecking alone cannot detect an omitted serialized field.70 71Use a server route when the raw HTTP contract is the product: webhooks, third-party clients, feeds, file responses, or a public REST API. When the Start UI and a server route share data, call one server-side service from both instead of making the SSR loader fetch its own API route.72 73Before finishing, test the initial SSR request, client navigation, mutation followed by refresh, and a direct anonymous request to every protected endpoint.74 75## Project Setup76 77### 1. Install Dependencies78 79```bash80npm i @tanstack/react-start @tanstack/react-router react react-dom81npm i -D vite @vitejs/plugin-react typescript82```83 84### 2. Configure Vite85 86```ts87// vite.config.ts88import { defineConfig } from 'vite'89import { tanstackStart } from '@tanstack/react-start/plugin/vite'90import viteReact from '@vitejs/plugin-react'91 92export default defineConfig({93  plugins: [94    // MUST come before react()95    tanstackStart(),96    viteReact(),97  ],98})99```100 101### 3. Create Router Factory102 103```tsx104// src/router.tsx105import { createRouter } from '@tanstack/react-router'106import { routeTree } from './routeTree.gen'107 108export function getRouter() {109  const router = createRouter({110    routeTree,111    scrollRestoration: true,112  })113 114  return router115}116```117 118### 4. Create Root Route with Document Shell119 120```tsx121// src/routes/__root.tsx122import type { ReactNode } from 'react'123import {124  Outlet,125  createRootRoute,126  HeadContent,127  Scripts,128} from '@tanstack/react-router'129 130export const Route = createRootRoute({131  head: () => ({132    meta: [133      { charSet: 'utf-8' },134      { name: 'viewport', content: 'width=device-width, initial-scale=1' },135      { title: 'My App' },136    ],137  }),138  component: RootComponent,139})140 141function RootComponent() {142  return (143    <html>144      <head>145        <HeadContent />146      </head>147      <body>148        <Outlet />149        <Scripts />150      </body>151    </html>152  )153}154```155 156### 5. Create Index Route with Server Function157 158```tsx159// src/routes/index.tsx160import { createFileRoute } from '@tanstack/react-router'161import { createServerFn } from '@tanstack/react-start'162 163const getGreeting = createServerFn({ method: 'GET' }).handler(async () => {164  return { message: 'Hello from the server!' }165})166 167export const Route = createFileRoute('/')({168  loader: () => getGreeting(),169  component: HomePage,170})171 172function HomePage() {173  const data = Route.useLoaderData()174  return <h1>{data.message}</h1>175}176```177 178## Common Mistakes179 180### 1. CRITICAL: React plugin before Start plugin in Vite config181 182```ts183// WRONG — route generation and server function compilation fail184plugins: [react(), tanstackStart()]185 186// CORRECT — Start plugin must come first187plugins: [tanstackStart(), react()]188```189 190### 2. HIGH: Enabling verbatimModuleSyntax in tsconfig191 192`verbatimModuleSyntax` causes server bundles to leak into client bundles. Keep it disabled.193 194### 3. HIGH: Missing Scripts component in root route195 196The `<Scripts />` component must be rendered in the `<body>` of the root route. Without it, client-side JavaScript does not load and hydration fails.197 198```tsx199// WRONG — no Scripts200function RootComponent() {201  return (202    <html>203      <head>204        <HeadContent />205      </head>206      <body>207        <Outlet />208      </body>209    </html>210  )211}212 213// CORRECT — Scripts in body214function RootComponent() {215  return (216    <html>217      <head>218        <HeadContent />219      </head>220      <body>221        <Outlet />222        <Scripts />223      </body>224    </html>225  )226}227```228 229## Version Note230 231This skill targets `@tanstack/start-client-core` v1.170.14.232