TanStack Start en 2026: La Stack React Moderna con Router y Query

// app/router.tsx — TanStack Router es 100% type-safe en 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',
  // loader type-safe: params inferidos automáticamente
  loader: async ({ params }) => {
    return queryClient.ensureQueryData({
      queryKey: ['post', params.postId],
      queryFn: () => fetchPost(params.postId)
    })
  },
  component: PostPage
})

// ❌ Error en compile time si navegas a ruta inexistente
// <Link to="/post/123">  // → Type error: did you mean "/posts/$postId"?
<Link to="/posts/$postId" params={{ postId: '123' }}>Post</Link>

// routes/posts.$postId.tsx — validación de search params en 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 dentro del loader — cache compartido con el cliente
    return queryClient.ensureQueryData(postQuery(params.postId, deps.tab))
  },
  component: PostComponent
})

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

// lib/queries.ts — queryOptions reutilizable (SSR + CSR comparten clave)
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 — evita refetch innecesario
})

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

// En el componente (CSR): lectura instantánea desde cache hidratado
function PostComponent() {
  const { data } = useSuspenseQuery(postQuery(postId, 'overview'))
  // 0ms — ya está en cache por el SSR
}

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

# Estructura generada:
# app/
#   routes/
#     __root.tsx        # Layout raíz
#     index.tsx         # /
#     posts.$postId.tsx # /posts/:id con loader + search schema
#   router.tsx          # createRouter + QueryClient
#   ssr.tsx             # entry SSR (Vinxi)

// 1. Rutas: 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
// Con Hono o Nitro dentro de Start (mismo handler)
// 3. Middleware: middleware.ts → router middleware + server functions
// 4. Imágenes: next/image → vite-imagetools + unpic
// 5. Deploy: vercel.json → nitro.config.ts (target: vercel | cloudflare | node)

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

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

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