tanstack-start — Cursor rule: what it does, how to install

---
description: "TanStack Start full-stack React framework using server functions, API routes, SSR, streaming with defer(), and multi-platform deployment via Vinxi/Nitro"
globs: ["src/routes/**/*", "src/server/**/*", "app.config.ts"]
alwaysApply: false
---
You are an expert in TanStack Start, TanStack Router, React, TypeScript, and full-stack type-safe web applications.

## Core Principles
- TanStack Start = TanStack Router + Vinxi (Vite + Nitro) for full-stack React
- `createServerFn` is the primary way to run server-side logic with end-to-end type safety
- All TanStack Router conventions apply — file-based routing, loaders, search params, etc.
- Server functions replace REST endpoints for most use cases
- Streaming + Suspense are first-class — use `defer()` for non-critical data

## app.config.ts
```ts
import { defineConfig } from '@tanstack/start/config'
import tsConfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  vite: { plugins: [tsConfigPaths()] },
  server: {
    preset: 'node-server', // or: 'vercel', 'netlify', 'bun', 'cloudflare-pages'
  },
})
```

## Root Route HTML Shell
```tsx
// src/routes/__root.tsx
export const Route = createRootRoute({
  component: () => (
    <html lang="en">
      <head />
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  ),
})
```

## Server Functions
```ts
// src/server/functions/posts.ts
export const getPost = createServerFn()
  .validator(z.object({ id: z.string() }))
  .handler(async ({ data }) => {
    const post = await db.post.findUnique({ where: { id: data.id } })
    if (!post) throw new Error('Post not found')
    return post
  })

export const createPost = createServerFn()
  .validator(z.object({ title: z.string().min(1), body: z.string() }))
  .handler(async ({ data }) => db.post.create({ data }))
```

## Using Server Functions in Routes
```tsx
export const Route = createFileRoute('/posts/$postId')({
  loader: ({ params }) => getPost({ data: { id: params.postId } }),
  component: PostDetail,
})
```

## Mutations with Server Functions
```tsx
const mutation = useMutation({
  mutationFn: (input: { title: string; body: string }) => createPost({ data: input }),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
})
```

## API Routes (for webhooks / raw HTTP)
```ts
// src/routes/api/webhook.ts
export const Route = createAPIFileRoute('/api/webhook')({
  POST: async ({ request }) => {
    const body = await request.json()
    return Response.json({ received: true })
  },
})
```

## Streaming with defer()
```tsx
export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await getPost({ data: { id: params.postId } })  // awaited = critical
    const comments = getComments({ data: { postId: params.postId } })  // not awaited
    return { post, comments: defer(comments) }
  },
  component: PostDetail,
})

function PostDetail() {
  const { post, comments } = Route.useLoaderData()
  return (
    <div>
      <h1>{post.title}</h1>
      <Suspense fallback={<CommentsSkeleton />}>
        <Await promise={comments}>{(c) => <CommentsList comments={c} />}</Await>
      </Suspense>
    </div>
  )
}
```

## Environment Variables
- Access server-only vars via `process.env` inside server functions only
- Use `import.meta.env.VITE_*` for client-exposed variables
- Never access `process.env` in client components

## Deployment Targets
Configure `server.preset` in `app.config.ts`:
- `node-server` — default Node.js
- `vercel` — Vercel serverless/edge
- `netlify` — Netlify Functions
- `bun` — Bun runtime
- `cloudflare-pages` — Cloudflare Pages + Workers