TanStack Start: A Serious Next.js Competitor Built on Vite

┌─────────────────────────────────────────────┐
│               Your Application               │
├─────────────────────────────────────────────┤
│                                              │
│  ┌──────────────┐    ┌───────────────────┐  │
│  │ TanStack     │    │ Server Functions   │  │
│  │ Router       │    │ (type-safe RPC)    │  │
│  │              │    │                    │  │
│  │ - File-based │    │ - createServerFn() │  │
│  │ - Type-safe  │    │ - Validated I/O    │  │
│  │ - Loaders    │    │ - Middleware        │  │
│  └──────────────┘    └───────────────────┘  │
│                                              │
├─────────────────────────────────────────────┤
│  Vinxi (Server Layer — powered by Nitro)     │
├─────────────────────────────────────────────┤
│  Vite (Build + Dev Server)                   │
└─────────────────────────────────────────────┘

app/
├── routes/
│   ├── __root.tsx           # Root layout
│   ├── index.tsx             # /
│   ├── about.tsx             # /about
│   ├── blog/
│   │   ├── index.tsx         # /blog
│   │   └── $slug.tsx         # /blog/:slug
│   ├── dashboard/
│   │   ├── route.tsx         # /dashboard (layout)
│   │   ├── index.tsx         # /dashboard
│   │   └── settings.tsx      # /dashboard/settings
│   └── api/
│       └── health.ts         # /api/health

// This is fully type-checked — $slug is typed as string
// Search params are typed. Loader data is typed.
export const Route = createFileRoute('/blog/$slug')({
  // Validate and type search params
  validateSearch: (search: Record<string, unknown>) => ({
    page: Number(search.page) || 1,
    sort: (search.sort as 'date' | 'title') || 'date',
  }),

  // Loader runs on server (SSR) and client (navigation)
  loader: async ({ params, context }) => {
    // params.slug is typed as string
    const post = await fetchPost(params.slug)
    if (!post) throw notFound()
    return { post }
  },

  component: BlogPost,
})

function BlogPost() {
  // All of this is fully typed — no 'as' casts, no runtime checks
  const { post } = Route.useLoaderData()
  const { page, sort } = Route.useSearch()
  const { slug } = Route.useParams()

  return (
    <article>
      <h1>{post.title}</h1>
      <p>Viewing page {page}, sorted by {sort}</p>
    </article>
  )
}

import { Link } from '@tanstack/react-router'

// This is type-checked — typos in the path cause compile errors
<Link to="/blog/$slug" params={{ slug: 'my-post' }}>
  Read Post
</Link>

// Search params are type-checked too
<Link
  to="/blog/$slug"
  params={{ slug: 'my-post' }}
  search={{ page: 2, sort: 'title' }}
>
  Page 2
</Link>

// This would be a TypeScript error:
<Link to="/blog/$slug" params={{ id: 'my-post' }}>
  {/* Error: 'id' does not exist, expected 'slug' */}
</Link>

export const Route = createFileRoute('/products')({
  validateSearch: (search: Record<string, unknown>) => ({
    category: (search.category as string) || 'all',
    minPrice: Number(search.minPrice) || 0,
    maxPrice: Number(search.maxPrice) || Infinity,
    sort: (search.sort as 'price' | 'name' | 'rating') || 'name',
    page: Number(search.page) || 1,
  }),

  loaderDeps: ({ search }) => ({
    category: search.category,
    minPrice: search.minPrice,
    maxPrice: search.maxPrice,
    sort: search.sort,
    page: search.page,
  }),

  loader: async ({ deps }) => {
    // deps is fully typed from validateSearch
    return fetchProducts(deps)
  },

  component: ProductList,
})

function ProductList() {
  const products = Route.useLoaderData()
  const search = Route.useSearch()
  const navigate = Route.useNavigate()

  return (
    <div>
      <select
        value={search.sort}
        onChange={(e)=>
          navigate({
            search: (prev)=> ({
              ...prev,
              sort: e.target.value as 'price' | 'name' | 'rating',
            }),
          })
        }
      >
        <option value="name">Name</option>
        <option value="price">Price</option>
        <option value="rating">Rating</option>
      </select>
      {/* Product list */}
    </div>
  )
}

import { createServerFn } from '@tanstack/start'
import { z } from 'zod'

// Define a server function with input validation
const createComment = createServerFn({ method: 'POST' })
  .validator(
    z.object({
      postId: z.string().uuid(),
      body: z.string().min(1).max(5000),
      parentId: z.string().uuid().optional(),
    })
  )
  .handler(async ({ data, context }) => {
    // data is typed: { postId: string, body: string, parentId?: string }
    const user = context.user
    if (!user) throw new Error('Unauthorized')

    const comment = await db.comments.create({
      data: {
        ...data,
        authorId: user.id,
      },
    })

    return comment
  })

// Use it in a component — fully typed
function CommentForm({ postId }: { postId: string }) {
  const mutation = useMutation({
    mutationFn: (body: string) =>
      createComment({ data: { postId, body } }),
    // Return type is inferred from the handler
  })

  return (
    <form
      onSubmit={(e)=> {
        e.preventDefault()
        const body= new FormData(e.currentTarget).get('body') as string
        mutation.mutate(body)
      }}
    >
      <textarea name="body" required />
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? 'Posting...' : 'Post Comment'}
      </button>
    </form>
  )
}

import { createMiddleware, createServerFn } from '@tanstack/start'

// Auth middleware — reusable across server functions
const authMiddleware = createMiddleware().handler(async ({ next, context }) => {
  const session = await getSession(context.request)
  if (!session?.user) {
    throw new Error('Unauthorized')
  }
  return next({ context: { user: session.user } })
})

// Rate limit middleware
const rateLimitMiddleware = createMiddleware().handler(
  async ({ next, context }) => {
    const ip = context.request.headers.get('x-forwarded-for')
    await checkRateLimit(ip, { max: 100, window: '1m' })
    return next()
  }
)

// Compose middleware into a server function
const updateProfile = createServerFn({ method: 'POST' })
  .middleware([authMiddleware, rateLimitMiddleware])
  .validator(
    z.object({
      displayName: z.string().min(1).max(100),
      bio: z.string().max(500).optional(),
    })
  )
  .handler(async ({ data, context }) => {
    // context.user is typed from authMiddleware
    return db.users.update({
      where: { id: context.user.id },
      data,
    })
  })

pnpm create @tanstack/start my-app
cd my-app
pnpm install

my-app/
├── app/
│   ├── routes/
│   │   ├── __root.tsx
│   │   ├── index.tsx
│   │   └── posts/
│   │       ├── index.tsx
│   │       └── $postId.tsx
│   ├── client.tsx
│   ├── router.tsx
│   ├── routeTree.gen.ts    # Auto-generated route types
│   └── ssr.tsx
├── app.config.ts
├── tsconfig.json
└── package.json

// app/routes/__root.tsx
import { Outlet, createRootRoute } from '@tanstack/react-router'

export const Route = createRootRoute({
  component: RootLayout,
})

function RootLayout() {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scal=1" />
        <title>My App</title>
      </head>
      <body>
        <nav>
          <Link to="/">Home</Link>
          <Link to="/posts">Posts</Link>
        </nav>
        <main>
          <Outlet />
        </main>
      </body>
    </html>
  )
}

// app/routes/posts/$postId.tsx
import { createFileRoute, notFound } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/start'

const fetchPost = createServerFn({ method: 'GET' })
  .validator((postId: string) => postId)
  .handler(async ({ data: postId }) => {
    const post = await db.posts.findUnique({ where: { id: postId } })
    if (!post) throw notFound()
    return post
  })

export const Route = createFileRoute('/posts/$postId')({
  loader: ({ params }) => fetchPost({ data: params.postId }),

  component: PostPage,

  notFoundComponent: () => <p>Post not found.</p>,
})

function PostPage() {
  const post = Route.useLoaderData()

  return (
    <article>
      <h1>{post.title}</h1>
      <time>{new Date(post.createdAt).toLocaleDateString()}</time>
      <div>{post.content}</div>
    </article>
  )
}

// app.config.ts
import { defineConfig } from '@tanstack/start/config'

export default defineConfig({
  server: {
    preset: 'node-server',     // or 'vercel', 'netlify', 'cloudflare', etc.
    prerender: {
      routes: ['/'],            // Prerender specific routes
    },
  },
  vite: {
    // Standard Vite config
    css: {
      postcss: './postcss.config.js',
    },
  },
})