start-core

TanStack Start Core

TanStack 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.

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. 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. CRITICAL: Types are FULLY INFERRED. Never cast, never annotate inferred values.

Use 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.

Sub-Skills

Quick Decision Tree

Need to run code exclusively on the server (DB, secrets)?
  → start-core/server-functions

Need auth checks, logging, or shared logic across server functions?
  → start-core/middleware

Need to add login, sessions, OAuth, CSRF, password reset?
  → start-core/auth-server-primitives

Need to understand where code runs (server vs client)?
  → start-core/execution-model

Need a REST API endpoint (GET/POST/PUT/DELETE)?
  → start-core/server-routes

Need to deploy, configure SSR, or prerender?
  → start-core/deployment

Full-Stack Delivery Workflow

For application data loaded by a Start route:

1. Put database, filesystem, secrets, and persistence code behind createServerFn.
2. Call the server function directly from the route loader. Do not self-fetch a relative /api/... URL from an SSR loader.
3. Validate every input and enforce auth in the server function or middleware. beforeLoad only protects route UX.
4. After a mutation resolves, invalidate the router or the external query cache and await the refresh when the UI must be current before continuing.
5. For schema changes, update storage, validation, handler serialization, loader, and UI. Assert the actual runtime payload; typechecking alone cannot detect an omitted serialized field.

Use 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.

Before finishing, test the initial SSR request, client navigation, mutation followed by refresh, and a direct anonymous request to every protected endpoint.

Project Setup

1. Install Dependencies

npm i @tanstack/react-start @tanstack/react-router react react-dom
npm i -D vite @vitejs/plugin-react typescript

2. Configure Vite

// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    // MUST come before react()
    tanstackStart(),
    viteReact(),
  ],
})

3. Create Router Factory

// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  const router = createRouter({
    routeTree,
    scrollRestoration: true,
  })

  return router
}

4. Create Root Route with Document Shell

// src/routes/__root.tsx
import type { ReactNode } from 'react'
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from '@tanstack/react-router'

export const Route = createRootRoute({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { title: 'My App' },
    ],
  }),
  component: RootComponent,
})

function RootComponent() {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}

5. Create Index Route with Server Function

// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start'

const getGreeting = createServerFn({ method: 'GET' }).handler(async () => {
  return { message: 'Hello from the server!' }
})

export const Route = createFileRoute('/')({
  loader: () => getGreeting(),
  component: HomePage,
})

function HomePage() {
  const data = Route.useLoaderData()
  return <h1>{data.message}</h1>
}

Common Mistakes

1. CRITICAL: React plugin before Start plugin in Vite config

// WRONG — route generation and server function compilation fail
plugins: [react(), tanstackStart()]

// CORRECT — Start plugin must come first
plugins: [tanstackStart(), react()]

2. HIGH: Enabling verbatimModuleSyntax in tsconfig

verbatimModuleSyntax causes server bundles to leak into client bundles. Keep it disabled.

3. HIGH: Missing Scripts component in root route

The <Scripts /> component must be rendered in the <body> of the root route. Without it, client-side JavaScript does not load and hydration fails.

// WRONG — no Scripts
function RootComponent() {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
      </body>
    </html>
  )
}

// CORRECT — Scripts in body
function RootComponent() {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}

Version Note

This skill targets @tanstack/start-client-core v1.170.14.