@tanstack/start-client-core 1.166.11 → 1.166.13

package/skills/start-core/server-functions/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: start-core/server-functions
+description: >-
+  createServerFn (GET/POST), inputValidator (Zod or function),
+  useServerFn hook, server context utilities (getRequest,
+  getRequestHeader, setResponseHeader, setResponseStatus), error
+  handling (throw errors, redirect, notFound), streaming, FormData
+  handling, file organization (.functions.ts, .server.ts).
+type: sub-skill
+library: tanstack-start
+library_version: '1.166.2'
+requires:
+  - start-core
+sources:
+  - TanStack/router:docs/start/framework/react/guide/server-functions.md
+---
+
+# Server Functions
+
+Server functions are type-safe RPCs created with `createServerFn`. They run exclusively on the server but can be called from anywhere — loaders, components, hooks, event handlers, or other server functions.
+
+> **CRITICAL**: Loaders are ISOMORPHIC — they run on BOTH client and server. Database queries, file system access, and secret API keys MUST go inside `createServerFn`, NOT in loaders directly.
+> **CRITICAL**: Do not use `"use server"` directives, `getServerSideProps`, or any Next.js/Remix server patterns. TanStack Start uses `createServerFn` exclusively.
+
+## Basic Usage
+
+```tsx
+import { createServerFn } from '@tanstack/react-start'
+
+// GET (default)
+const getData = createServerFn().handler(async () => {
+  return { message: 'Hello from server!' }
+})
+
+// POST
+const saveData = createServerFn({ method: 'POST' }).handler(async () => {
+  return { success: true }
+})
+```
+
+## Calling from Loaders
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+
+const getPosts = createServerFn({ method: 'GET' }).handler(async () => {
+  const posts = await db.query('SELECT * FROM posts')
+  return { posts }
+})
+
+export const Route = createFileRoute('/posts')({
+  loader: () => getPosts(),
+  component: PostList,
+})
+
+function PostList() {
+  const { posts } = Route.useLoaderData()
+  return (
+    <ul>
+      {posts.map((p) => (
+        <li key={p.id}>{p.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Calling from Components
+
+Use the `useServerFn` hook to call server functions from event handlers:
+
+```tsx
+import { useServerFn } from '@tanstack/react-start'
+
+const deletePost = createServerFn({ method: 'POST' })
+  .inputValidator((data: { id: string }) => data)
+  .handler(async ({ data }) => {
+    await db.delete('posts').where({ id: data.id })
+    return { success: true }
+  })
+
+function DeleteButton({ postId }: { postId: string }) {
+  const deletePostFn = useServerFn(deletePost)
+
+  return (
+    <button onClick={() => deletePostFn({ data: { id: postId } })}>
+      Delete
+    </button>
+  )
+}
+```
+
+## Input Validation
+
+### Basic Validator
+
+```tsx
+const greetUser = createServerFn({ method: 'GET' })
+  .inputValidator((data: { name: string }) => data)
+  .handler(async ({ data }) => {
+    return `Hello, ${data.name}!`
+  })
+
+await greetUser({ data: { name: 'John' } })
+```
+
+### Zod Validator
+
+```tsx
+import { z } from 'zod'
+
+const createUser = createServerFn({ method: 'POST' })
+  .inputValidator(
+    z.object({
+      name: z.string().min(1),
+      age: z.number().min(0),
+    }),
+  )
+  .handler(async ({ data }) => {
+    return `Created user: ${data.name}, age ${data.age}`
+  })
+```
+
+### FormData
+
+```tsx
+const submitForm = createServerFn({ method: 'POST' })
+  .inputValidator((data) => {
+    if (!(data instanceof FormData)) {
+      throw new Error('Expected FormData')
+    }
+    return {
+      name: data.get('name')?.toString() || '',
+      email: data.get('email')?.toString() || '',
+    }
+  })
+  .handler(async ({ data }) => {
+    return { success: true }
+  })
+```
+
+## Error Handling
+
+### Errors
+
+```tsx
+const riskyFunction = createServerFn().handler(async () => {
+  throw new Error('Something went wrong!')
+})
+
+try {
+  await riskyFunction()
+} catch (error) {
+  console.log(error.message) // "Something went wrong!"
+}
+```
+
+### Redirects
+
+```tsx
+import { redirect } from '@tanstack/react-router'
+
+const requireAuth = createServerFn().handler(async () => {
+  const user = await getCurrentUser()
+  if (!user) {
+    throw redirect({ to: '/login' })
+  }
+  return user
+})
+```
+
+### Not Found
+
+```tsx
+import { notFound } from '@tanstack/react-router'
+
+const getPost = createServerFn()
+  .inputValidator((data: { id: string }) => data)
+  .handler(async ({ data }) => {
+    const post = await db.findPost(data.id)
+    if (!post) {
+      throw notFound()
+    }
+    return post
+  })
+```
+
+## Server Context Utilities
+
+Access request/response details inside server function handlers:
+
+```tsx
+import { createServerFn } from '@tanstack/react-start'
+import {
+  getRequest,
+  getRequestHeader,
+  setResponseHeaders,
+  setResponseStatus,
+} from '@tanstack/react-start/server'
+
+const getCachedData = createServerFn({ method: 'GET' }).handler(async () => {
+  const request = getRequest()
+  const authHeader = getRequestHeader('Authorization')
+
+  setResponseHeaders({
+    'Cache-Control': 'public, max-age=300',
+  })
+  setResponseStatus(200)
+
+  return fetchData()
+})
+```
+
+Available utilities:
+
+- `getRequest()` — full Request object
+- `getRequestHeader(name)` — single request header
+- `setResponseHeader(name, value)` — single response header
+- `setResponseHeaders(headers)` — multiple response headers
+- `setResponseStatus(code)` — HTTP status code
+
+## File Organization
+
+```text
+src/utils/
+├── users.functions.ts   # createServerFn wrappers (safe to import anywhere)
+├── users.server.ts      # Server-only helpers (DB queries, internal logic)
+└── schemas.ts           # Shared validation schemas (client-safe)
+```
+
+```tsx
+// users.server.ts — server-only helpers
+import { db } from '~/db'
+
+export async function findUserById(id: string) {
+  return db.query.users.findFirst({ where: eq(users.id, id) })
+}
+```
+
+```tsx
+// users.functions.ts — server functions
+import { createServerFn } from '@tanstack/react-start'
+import { findUserById } from './users.server'
+
+export const getUser = createServerFn({ method: 'GET' })
+  .inputValidator((data: { id: string }) => data)
+  .handler(async ({ data }) => {
+    return findUserById(data.id)
+  })
+```
+
+Static imports of server functions are safe — the build replaces implementations with RPC stubs in client bundles.
+
+## Common Mistakes
+
+### 1. CRITICAL: Putting server-only code in loaders
+
+```tsx
+// WRONG — loader is ISOMORPHIC, runs on BOTH client and server
+export const Route = createFileRoute('/posts')({
+  loader: async () => {
+    const posts = await db.query('SELECT * FROM posts')
+    return { posts }
+  },
+})
+
+// CORRECT — use createServerFn for server-only logic
+const getPosts = createServerFn({ method: 'GET' }).handler(async () => {
+  const posts = await db.query('SELECT * FROM posts')
+  return { posts }
+})
+
+export const Route = createFileRoute('/posts')({
+  loader: () => getPosts(),
+})
+```
+
+### 2. CRITICAL: Using Next.js/Remix server patterns
+
+```tsx
+// WRONG — "use server" is a React directive, not used in TanStack Start
+'use server'
+export async function getUser() { ... }
+
+// WRONG — getServerSideProps is Next.js
+export async function getServerSideProps() { ... }
+
+// CORRECT — TanStack Start uses createServerFn
+const getUser = createServerFn({ method: 'GET' })
+  .handler(async () => { ... })
+```
+
+### 3. HIGH: Dynamic imports for server functions
+
+```tsx
+// WRONG — can cause bundler issues
+const { getUser } = await import('~/utils/users.functions')
+
+// CORRECT — static imports are safe, build handles environment shaking
+import { getUser } from '~/utils/users.functions'
+```
+
+### 4. HIGH: Awaiting server function without calling it
+
+`createServerFn` returns a function — it must be invoked with `()`:
+
+```tsx
+// WRONG — getItems is a function, not a Promise
+const data = await getItems
+
+// CORRECT — call the function
+const data = await getItems()
+
+// With validated input
+const data = await getItems({ data: { id: '1' } })
+```
+
+### 5. MEDIUM: Not using useServerFn for component calls
+
+When calling server functions from event handlers in components, use `useServerFn` to get proper React integration:
+
+```tsx
+// WRONG — direct call doesn't integrate with React lifecycle
+<button onClick={() => deletePost({ data: { id } })}>Delete</button>
+
+// CORRECT — useServerFn integrates with React
+const deletePostFn = useServerFn(deletePost)
+<button onClick={() => deletePostFn({ data: { id } })}>Delete</button>
+```
+
+## Cross-References
+
+- [start-core/execution-model](../execution-model/SKILL.md) — understanding where code runs
+- [start-core/middleware](../middleware/SKILL.md) — composing server functions with middleware

package/skills/start-core/server-routes/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: start-core/server-routes
+description: >-
+  Server-side API endpoints using the server property on
+  createFileRoute, HTTP method handlers (GET, POST, PUT, DELETE),
+  createHandlers for per-handler middleware, handler context
+  (request, params, context), request body parsing, response
+  helpers, file naming for API routes.
+type: sub-skill
+library: tanstack-start
+library_version: '1.166.2'
+requires:
+  - start-core
+sources:
+  - TanStack/router:docs/start/framework/react/guide/server-routes.md
+---
+
+# Server Routes
+
+Server routes are API endpoints defined alongside app routes in the `src/routes` directory. They use the `server` property on `createFileRoute` and handle raw HTTP requests.
+
+## Basic Server Route
+
+```ts
+// src/routes/api/hello.ts
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/api/hello')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        return new Response('Hello, World!')
+      },
+    },
+  },
+})
+```
+
+## Combining Server Route and App Route
+
+The same file can define both a server route and a UI route:
+
+```tsx
+// src/routes/hello.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { useState } from 'react'
+
+export const Route = createFileRoute('/hello')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const body = await request.json()
+        return Response.json({ message: `Hello, ${body.name}!` })
+      },
+    },
+  },
+  component: HelloComponent,
+})
+
+function HelloComponent() {
+  const [reply, setReply] = useState('')
+  return (
+    <button
+      onClick={() => {
+        fetch('/hello', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name: 'Tanner' }),
+        })
+          .then((res) => res.json())
+          .then((data) => setReply(data.message))
+      }}
+    >
+      Say Hello {reply && `- ${reply}`}
+    </button>
+  )
+}
+```
+
+## File Route Conventions
+
+Server routes follow TanStack Router file-based routing conventions:
+
+| File                        | Route                         |
+| --------------------------- | ----------------------------- |
+| `routes/users.ts`           | `/users`                      |
+| `routes/users/$id.ts`       | `/users/$id`                  |
+| `routes/users/$id/posts.ts` | `/users/$id/posts`            |
+| `routes/api/file/$.ts`      | `/api/file/$` (splat)         |
+| `routes/my-script[.]js.ts`  | `/my-script.js` (escaped dot) |
+
+## Unique Route Paths
+
+Each route can only have a single handler file. These would conflict:
+
+- `routes/users.ts`
+- `routes/users.index.ts`
+- `routes/users/index.ts`
+
+## Handler Context
+
+Each handler receives:
+
+- `request` — the incoming [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object
+- `params` — dynamic path parameters
+- `context` — context from middleware
+- `pathname` — the matched pathname
+- `next` — call to fall through to SSR (returns a `Response`)
+
+## Dynamic Path Params
+
+```ts
+// routes/users/$id.ts
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/users/$id')({
+  server: {
+    handlers: {
+      GET: async ({ params }) => {
+        return new Response(`User ID: ${params.id}`)
+      },
+    },
+  },
+})
+```
+
+## Splat/Wildcard Params
+
+```ts
+// routes/file/$.ts
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/file/$')({
+  server: {
+    handlers: {
+      GET: async ({ params }) => {
+        return new Response(`File: ${params._splat}`)
+      },
+    },
+  },
+})
+```
+
+## Request Body Handling
+
+```ts
+export const Route = createFileRoute('/api/users')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const body = await request.json()
+        return Response.json({ created: body.name })
+      },
+    },
+  },
+})
+```
+
+Other body methods: `request.text()`, `request.formData()`.
+
+## JSON Responses
+
+```ts
+// Using Response.json helper
+handlers: {
+  GET: async () => {
+    return Response.json({ message: 'Hello!' })
+  },
+}
+```
+
+## Status Codes and Headers
+
+```ts
+handlers: {
+  GET: async ({ params }) => {
+    const user = await findUser(params.id)
+    if (!user) {
+      return new Response('Not found', { status: 404 })
+    }
+    return Response.json(user)
+  },
+}
+```
+
+```ts
+handlers: {
+  GET: async () => {
+    return new Response('Hello', {
+      headers: { 'Content-Type': 'text/plain' },
+    })
+  },
+}
+```
+
+## Middleware on Server Routes
+
+### All handlers
+
+```tsx
+export const Route = createFileRoute('/api/admin')({
+  server: {
+    middleware: [authMiddleware, loggerMiddleware],
+    handlers: {
+      GET: async ({ context }) => Response.json(context.user),
+      POST: async ({ request, context }) => {
+        /* ... */
+      },
+    },
+  },
+})
+```
+
+### Specific handlers with createHandlers
+
+```tsx
+export const Route = createFileRoute('/api/data')({
+  server: {
+    handlers: ({ createHandlers }) =>
+      createHandlers({
+        GET: async () => Response.json({ public: true }),
+        POST: {
+          middleware: [authMiddleware],
+          handler: async ({ context }) => {
+            return Response.json({ user: context.session.user })
+          },
+        },
+      }),
+  },
+})
+```
+
+### Combined route-level and handler-specific
+
+```tsx
+export const Route = createFileRoute('/api/posts')({
+  server: {
+    middleware: [authMiddleware], // runs first for all
+    handlers: ({ createHandlers }) =>
+      createHandlers({
+        GET: async () => Response.json([]),
+        POST: {
+          middleware: [validationMiddleware], // runs after auth, POST only
+          handler: async ({ request }) => {
+            const body = await request.json()
+            return Response.json({ created: true })
+          },
+        },
+      }),
+  },
+})
+```
+
+## Common Mistakes
+
+### 1. MEDIUM: Duplicate route paths
+
+```text
+# WRONG — both resolve to /users, causes error
+routes/users.ts
+routes/users/index.ts
+
+# CORRECT — pick one
+routes/users.ts
+```
+
+### 2. MEDIUM: Forgetting to await request body methods
+
+```ts
+// WRONG — body is a Promise, not the actual data
+const body = request.json()
+
+// CORRECT — await the promise
+const body = await request.json()
+```
+
+## Cross-References
+
+- [start-core/middleware](../middleware/SKILL.md) — middleware for server routes
+- [start-core/server-functions](../server-functions/SKILL.md) — alternative for RPC-style calls