TanStack Start in 2026: The Modern React Stack with Router and Query

// app/router.tsx — TanStack Router is 100% type-safe in 2026
import { createRouter, createRoute, createRootRoute } from '@tanstack/react-router'
import { QueryClient } from '@tanstack/react-query'

const rootRoute = createRootRoute({
  component: () => <Outlet />
})

const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/posts/$postId',
  // type-safe loader: params inferred automatically
  loader: async ({ params }) => {
    return queryClient.ensureQueryData({
      queryKey: ['post', params.postId],
      queryFn: () => fetchPost(params.postId)
    })
  },
  component: PostPage
})

// ❌ Compile-time error if you navigate to non-existing route
// <Link to="/post/123">  // → Type error: did you mean "/posts/$postId"?
<Link to="/posts/$postId" params={{ postId: '123' }}>Post</Link>

// routes/posts.$postId.tsx — search param validation in 2026
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'

const searchSchema = z.object({
  tab: z.enum(['overview', 'comments']).default('overview'),
  page: z.coerce.number().min(1).default(1),
})

export const Route = createFileRoute('/posts/$postId')({
  validateSearch: searchSchema,
  loaderDeps: ({ search }) => ({ tab: search.tab }),
  loader: async ({ params, deps }) => {
    // TanStack Query inside loader — shared cache with client
    return queryClient.ensureQueryData(postQuery(params.postId, deps.tab))
  },
  component: PostComponent
})

function PostComponent() {
  const { postId } = Route.useParams() // inferred string ✅
  const { tab } = Route.useSearch()    // 'overview' | 'comments' ✅
  const data = useSuspenseQuery(postQuery(postId, tab))
}

// lib/queries.ts — reusable queryOptions (SSR + CSR share key)
import { queryOptions } from '@tanstack/react-query'

export const postQuery = (id: string, tab: string) => queryOptions({
  queryKey: ['post', id, tab],
  queryFn: () => fetch(`/api/posts/${id}?tab=${tab}`).then(r => r.json()),
  staleTime: 1000 * 60 * 5, // 5 min — avoids unnecessary refetch
})

// In loader (SSR): prefetch + dehydrate
export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    await queryClient.ensureQueryData(postQuery(params.postId, 'overview'))
  }
})

// In component (CSR): instant read from hydrated cache
function PostComponent() {
  const { data } = useSuspenseQuery(postQuery(postId, 'overview'))
  // 0ms — already in cache from SSR
}

# Create TanStack Start app in 2026 (Vite 7 + Vinxi)
npm create tanstack@latest my-app
# Choose: TanStack Start → TypeScript → Tailwind → Add-ons: Query, Router

# Generated structure:
# app/
#   routes/
#     __root.tsx        # Root layout
#     index.tsx         # /
#     posts.$postId.tsx # /posts/:id with loader + search schema
#   router.tsx          # createRouter + QueryClient
#   ssr.tsx             # SSR entry (Vinxi)

// 1. Routes: app/post/[id]/page.tsx (Next) → app/routes/posts.$postId.tsx (Start)
// Next.js:
export default async function Page({ params }: { params: { id: string } }) {
  const post = await fetchPost(params.id)
  return <Post post={post} />
}
// TanStack Start:
export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => queryClient.ensureQueryData(postQuery(params.postId)),
  component: () => {
    const { data: post } = useSuspenseQuery(postQuery(Route.useParams().postId))
    return <Post post={post} />
  }
})

// 2. API: app/api/posts/route.ts → app/routes/api.posts.ts
// With Hono or Nitro inside Start (same handler)
// 3. Middleware: middleware.ts → router middleware + server functions
// 4. Images: next/image → vite-imagetools + unpic
// 5. Deploy: vercel.json → nitro.config.ts (target: vercel | cloudflare | node)

// app.config.ts — Vinxi + Vite 7 in 2026
import { defineConfig } from '@tanstack/start/config'

export default defineConfig({
  vite: {
    plugins: [tailwindcss(), tsconfigPaths()],
  },
  server: {
    preset: 'cloudflare', // or 'vercel', 'node-server', 'bun'
  },
  routers: {
    ssr: true,
    client: true,
  },
})

// Full stack 2026:
// - Router: TanStack Router 1.90 + Zod search validation
// - Data: TanStack Query v5 + queryOptions
// - Forms: TanStack Form + Zod (type-safe, no react-hook-form)
// - Table: TanStack Table v8 (headless)
// - Build: Vite 7 + Vinxi + Nitro
// - Deploy: Cloudflare Workers (18ms global) or Vercel
// - Auth: Better Auth or Clerk + server functions