101 lines
2.9 KiB
Markdown
101 lines
2.9 KiB
Markdown
# TanStack Start Reference
|
|
|
|
## CLI Commands
|
|
```bash
|
|
npm create @tanstack/start@latest # scaffold project
|
|
npm run dev # vite dev server
|
|
npm run build # production build
|
|
NITRO_PRESET=cloudflare-workers npm run build # deploy target
|
|
```
|
|
|
|
## app.config.ts
|
|
```ts
|
|
import { defineConfig } from '@tanstack/react-start/config'
|
|
export default defineConfig({
|
|
server: { preset: 'node-server' }, // or 'cloudflare-workers', 'vercel', etc.
|
|
tsr: { autoCodeSplitting: true },
|
|
})
|
|
```
|
|
|
|
## File-Based Routing Conventions
|
|
| Pattern | Route |
|
|
|---------|-------|
|
|
| `index.tsx` | `/` |
|
|
| `about.tsx` | `/about` |
|
|
| `posts.$postId.tsx` | `/posts/:postId` |
|
|
| `posts_.tsx` | Layout for `/posts/*` |
|
|
| `_layout.tsx` | Pathless layout group |
|
|
| `__root.tsx` | Root layout (required) |
|
|
|
|
`routeTree.gen.ts` is auto-generated — never edit manually.
|
|
|
|
## createFileRoute
|
|
```ts
|
|
export const Route = createFileRoute('/posts/$postId')({
|
|
validateSearch: z.object({ page: z.number().optional() }),
|
|
loader: async ({ params, context }) => fetchPost(params.postId),
|
|
pendingComponent: () => <Spinner />,
|
|
errorComponent: ({ error }) => <ErrorDisplay error={error} />,
|
|
component: PostComponent,
|
|
})
|
|
```
|
|
|
|
## createServerFn
|
|
```ts
|
|
const serverFn = createServerFn({ method: 'GET' })
|
|
.validator(z.object({ id: z.string() }))
|
|
.middleware([authMiddleware])
|
|
.handler(async ({ data, context }) => {
|
|
// context.user available from middleware
|
|
return db.find(data.id)
|
|
})
|
|
|
|
// Call from client or loader:
|
|
const result = await serverFn({ data: { id: '123' } })
|
|
```
|
|
|
|
## Middleware
|
|
```ts
|
|
import { createMiddleware } from '@tanstack/react-start'
|
|
|
|
export const authMiddleware = createMiddleware()
|
|
.server(async ({ next, context }) => {
|
|
const session = await getSession(context.request)
|
|
if (!session) throw redirect({ to: '/login' })
|
|
return next({ context: { user: session.user } })
|
|
})
|
|
```
|
|
|
|
Chain: `serverFn.middleware([logger, auth, rateLimit])`
|
|
|
|
## API Routes
|
|
```ts
|
|
// src/routes/api/health.ts
|
|
import { createAPIFileRoute } from '@tanstack/react-start/api'
|
|
export const APIRoute = createAPIFileRoute('/api/health')({
|
|
GET: () => new Response(JSON.stringify({ ok: true })),
|
|
POST: async ({ request }) => {
|
|
const body = await request.json()
|
|
return new Response(JSON.stringify(body))
|
|
},
|
|
})
|
|
```
|
|
|
|
## SSR Configuration
|
|
Default: client-side SPA. Opt-in SSR per route:
|
|
```ts
|
|
export const Route = createFileRoute('/')({
|
|
ssr: true, // enable SSR for this route
|
|
ssr: { streaming: true }, // enable streaming SSR
|
|
})
|
|
```
|
|
|
|
## Deploy Targets (Nitro Presets)
|
|
node-server, cloudflare-workers, cloudflare-pages, vercel, netlify, deno, bun, aws-lambda
|
|
|
|
## Key Packages
|
|
- `@tanstack/react-start` — framework
|
|
- `@tanstack/react-router` — routing (bundled)
|
|
- `@tanstack/react-query` — data fetching (optional but recommended)
|
|
- `vinxi` / `nitro` — server runtime (bundled)
|