tanstack-start-cursorrules-prompt-file — Cursor rule

---
description: "Cursor rules for TanStack Start full-stack React framework including server functions, API routes, streaming with defer(), SSR, and multi-platform deployment."
globs: **/*
alwaysApply: false
---
You are an expert in TanStack Start, TanStack Router, React, TypeScript, Vinxi, and full-stack type-safe web applications.

# TanStack Start Guidelines

## What is TanStack Start
TanStack Start is a full-stack React framework built on top of TanStack Router and Vinxi (Vite + Nitro). It provides SSR, streaming, server functions, and API routes with end-to-end type safety.

## Core Principles
- TanStack Start is file-based routing via TanStack Router — all routing conventions apply
- Server Functions (`createServerFn`) are the primary way to run server-side logic
- Full-stack type safety: server function inputs/outputs are typed end-to-end
- Streaming and Suspense are first-class — use them for progressive rendering
- Start is NOT an API-first framework — server functions replace REST endpoints for most use cases

## Project Structure
```
src/
  routes/
    __root.tsx          ← Root layout with HTML shell
    index.tsx           ← Home route
    posts/
      index.tsx
      $postId.tsx
  server/
    functions/          ← Server functions (recommended organization)
      posts.ts
      auth.ts
  lib/
    db.ts               ← Database client
    auth.ts             ← Auth utilities
app.config.ts           ← TanStack Start / Vinxi config
```

## 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 Setup
```tsx
// src/routes/__root.tsx
import { createRootRoute, ScrollRestoration, Scripts, Outlet } from '@tanstack/react-router'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { TanStackRouterDevtools } from '@tanstack/router-devtools'

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

function RootComponent() {
  return (
    <html lang="en">
      <head />
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
        {process.env.NODE_ENV === 'development' && (
          <>
            <TanStackRouterDevtools />
            <ReactQueryDevtools />
          </>
        )}
      </body>
    </html>
  )
}
```

## Server Functions
- Use `createServerFn` to define functions that always run on the server
- Validate inputs with Zod using `.validator()`
- Use `.handler()` for the implementation
- Server functions are called like regular async functions from components or loaders
```ts
// src/server/functions/posts.ts
import { createServerFn } from '@tanstack/start'
import { z } from 'zod'

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, context }) => {
    // context has access to request headers, cookies, etc.
    return db.post.create({ data })
  })
```

## Using Server Functions in Routes
```tsx
// src/routes/posts/$postId.tsx
import { createFileRoute } from '@tanstack/react-router'
import { getPost } from '../../server/functions/posts'

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

function PostDetail() {
  const post = Route.useLoaderData()
  return <article><h1>{post.title}</h1></article>
}
```

## Mutations with Server Functions
- Call server functions directly in event handlers or via TanStack Query mutations
```tsx
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { createPost } from '../../server/functions/posts'

function CreatePostForm() {
  const queryClient = useQueryClient()
  const mutation = useMutation({
    mutationFn: (input: { title: string; body: string }) =>
      createPost({ data: input }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['posts'] })
    },
  })

  return (
    <form onSubmit={(e) => {
      e.preventDefault()
      const fd = new FormData(e.currentTarget)
      mutation.mutate({ title: fd.get('title') as string, body: fd.get('body') as string })
    }}>
      <input name="title" />
      <textarea name="body" />
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? 'Creating...' : 'Create'}
      </button>
    </form>
  )
}
```

## API Routes
- Use `createAPIFileRoute` for raw HTTP endpoints (webhooks, third-party integrations)
- Place in `src/routes/api/` directory
```ts
// src/routes/api/webhook.ts
import { createAPIFileRoute } from '@tanstack/start/api'

export const Route = createAPIFileRoute('/api/webhook')({
  POST: async ({ request }) => {
    const body = await request.json()
    // handle webhook
    return Response.json({ received: true })
  },
})
```

## Streaming & Suspense
- Use `defer()` to stream non-critical data after the initial render
- Wrap deferred data consumers in `<Suspense>`
```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 (deferred)
    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}>
          {(resolved) => <CommentsList comments={resolved} />}
        </Await>
      </Suspense>
    </div>
  )
}
```

## Authentication
- Read cookies/headers in server functions using TanStack Start's server context
- Use `beforeLoad` in routes for auth guards
```ts
import { getWebRequest } from '@tanstack/start/server'

export const getSession = createServerFn().handler(async () => {
  const request = getWebRequest()
  const sessionToken = getCookie(request, 'session')
  return validateSession(sessionToken)
})
```

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

## Environment Variables
- Access server-only vars directly from `process.env` inside server functions
- Use Vite's `import.meta.env` for client-exposed variables (prefix with `VITE_`)
- Never access `process.env` in client components

## TanStack Query Integration
- Provide `QueryClient` via router context for loader-level prefetching
- Use `ensureQueryData` in loaders to populate cache before render
- This eliminates loading states for route-level data fetching