@benjavicente/start-client-core 1.167.9

package/skills/start-core/middleware/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: start-core/middleware
+description: >-
+  createMiddleware, request middleware (.server only), server function
+  middleware (.client + .server), context passing via next({ context }),
+  sendContext for client-server transfer, global middleware via
+  createStart in src/start.ts, middleware factories, method order
+  enforcement, fetch override precedence.
+type: sub-skill
+library: tanstack-start
+library_version: '1.166.2'
+requires:
+  - start-core
+  - start-core/server-functions
+sources:
+  - TanStack/router:docs/start/framework/react/guide/middleware.md
+---
+
+# Middleware
+
+Middleware customizes the behavior of server functions and server routes. It is composable — middleware can depend on other middleware to form a chain.
+
+> **CRITICAL**: TypeScript enforces method order: `middleware()` → `inputValidator()` → `client()` → `server()`. Wrong order causes type errors.
+> **CRITICAL**: Client context sent via `sendContext` is NOT validated by default. If you send dynamic user-generated data, validate it in server-side middleware before use.
+
+## Two Types of Middleware
+
+| Feature           | Request Middleware                           | Server Function Middleware               |
+| ----------------- | -------------------------------------------- | ---------------------------------------- |
+| Scope             | All server requests (SSR, routes, functions) | Server functions only                    |
+| Methods           | `.server()`                                  | `.client()`, `.server()`                 |
+| Input validation  | No                                           | Yes (`.inputValidator()`)                |
+| Client-side logic | No                                           | Yes                                      |
+| Created with      | `createMiddleware()`                         | `createMiddleware({ type: 'function' })` |
+
+Request middleware cannot depend on server function middleware. Server function middleware can depend on both types.
+
+## Request Middleware
+
+Runs on ALL server requests (SSR, server routes, server functions):
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createMiddleware } from '@benjavicente/react-start'
+
+const loggingMiddleware = createMiddleware().server(
+  async ({ next, context, request }) => {
+    console.log('Request:', request.url)
+    const result = await next()
+    return result
+  },
+)
+```
+
+## Server Function Middleware
+
+Has both client and server phases:
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createMiddleware } from '@benjavicente/react-start'
+
+const authMiddleware = createMiddleware({ type: 'function' })
+  .client(async ({ next }) => {
+    // Runs on client BEFORE the RPC call
+    const result = await next()
+    // Runs on client AFTER the RPC response
+    return result
+  })
+  .server(async ({ next, context }) => {
+    // Runs on server BEFORE the handler
+    const result = await next()
+    // Runs on server AFTER the handler
+    return result
+  })
+```
+
+## Attaching Middleware to Server Functions
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createServerFn } from '@benjavicente/react-start'
+
+const fn = createServerFn()
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    // context contains data from middleware
+    return { user: context.user }
+  })
+```
+
+## Context Passing via next()
+
+Pass context down the middleware chain:
+
+```tsx
+const authMiddleware = createMiddleware().server(async ({ next, request }) => {
+  const session = await getSession(request.headers)
+  if (!session) throw new Error('Unauthorized')
+
+  return next({
+    context: { session },
+  })
+})
+
+const roleMiddleware = createMiddleware()
+  .middleware([authMiddleware])
+  .server(async ({ next, context }) => {
+    console.log('Session:', context.session) // typed!
+    return next()
+  })
+```
+
+## Sending Context Between Client and Server
+
+### Client → Server (sendContext)
+
+```tsx
+const workspaceMiddleware = createMiddleware({ type: 'function' })
+  .client(async ({ next, context }) => {
+    return next({
+      sendContext: {
+        workspaceId: context.workspaceId,
+      },
+    })
+  })
+  .server(async ({ next, context }) => {
+    // workspaceId available here, but VALIDATE IT
+    console.log('Workspace:', context.workspaceId)
+    return next()
+  })
+```
+
+### Server → Client (sendContext in server)
+
+```tsx
+const serverTimer = createMiddleware({ type: 'function' }).server(
+  async ({ next }) => {
+    return next({
+      sendContext: {
+        timeFromServer: new Date(),
+      },
+    })
+  },
+)
+
+const clientLogger = createMiddleware({ type: 'function' })
+  .middleware([serverTimer])
+  .client(async ({ next }) => {
+    const result = await next()
+    console.log('Server time:', result.context.timeFromServer)
+    return result
+  })
+```
+
+## Input Validation in Middleware
+
+```tsx
+import { z } from 'zod'
+import { zodValidator } from '@benjavicente/zod-adapter'
+
+const workspaceMiddleware = createMiddleware({ type: 'function' })
+  .inputValidator(zodValidator(z.object({ workspaceId: z.string() })))
+  .server(async ({ next, data }) => {
+    console.log('Workspace:', data.workspaceId)
+    return next()
+  })
+```
+
+## Global Middleware
+
+Create `src/start.ts` to configure global middleware:
+
+```tsx
+// src/start.ts
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createStart, createMiddleware } from '@benjavicente/react-start'
+
+const requestLogger = createMiddleware().server(async ({ next, request }) => {
+  console.log(`${request.method} ${request.url}`)
+  return next()
+})
+
+const functionAuth = createMiddleware({ type: 'function' }).server(
+  async ({ next }) => {
+    // runs for every server function
+    return next()
+  },
+)
+
+export const startInstance = createStart(() => ({
+  requestMiddleware: [requestLogger],
+  functionMiddleware: [functionAuth],
+}))
+```
+
+## Using Middleware with Server Routes
+
+### All handlers in a route
+
+```tsx
+export const Route = createFileRoute('/api/users')({
+  server: {
+    middleware: [authMiddleware],
+    handlers: {
+      GET: async ({ context }) => Response.json(context.user),
+      POST: async ({ request }) => {
+        /* ... */
+      },
+    },
+  },
+})
+```
+
+### Specific handlers only
+
+```tsx
+export const Route = createFileRoute('/api/users')({
+  server: {
+    handlers: ({ createHandlers }) =>
+      createHandlers({
+        GET: async () => Response.json({ public: true }),
+        POST: {
+          middleware: [authMiddleware],
+          handler: async ({ context }) => {
+            return Response.json({ user: context.session.user })
+          },
+        },
+      }),
+  },
+})
+```
+
+## Middleware Factories
+
+Create parameterized middleware for reusable patterns like authorization:
+
+```tsx
+const authMiddleware = createMiddleware().server(async ({ next, request }) => {
+  const session = await auth.getSession({ headers: request.headers })
+  if (!session) throw new Error('Unauthorized')
+  return next({ context: { session } })
+})
+
+type Permissions = Record<string, string[]>
+
+function authorizationMiddleware(permissions: Permissions) {
+  return createMiddleware({ type: 'function' })
+    .middleware([authMiddleware])
+    .server(async ({ next, context }) => {
+      const granted = await auth.hasPermission(context.session, permissions)
+      if (!granted) throw new Error('Forbidden')
+      return next()
+    })
+}
+
+// Usage
+const getClients = createServerFn()
+  .middleware([authorizationMiddleware({ client: ['read'] })])
+  .handler(async () => {
+    return { message: 'The user can read clients.' }
+  })
+```
+
+## Custom Headers and Fetch
+
+### Setting headers from client middleware
+
+```tsx
+const authMiddleware = createMiddleware({ type: 'function' }).client(
+  async ({ next }) => {
+    return next({
+      headers: { Authorization: `Bearer ${getToken()}` },
+    })
+  },
+)
+```
+
+Headers merge across middleware. Later middleware overrides earlier. Call-site headers override all middleware headers.
+
+### Custom fetch
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import type { CustomFetch } from '@benjavicente/react-start'
+
+const loggingMiddleware = createMiddleware({ type: 'function' }).client(
+  async ({ next }) => {
+    const customFetch: CustomFetch = async (url, init) => {
+      console.log('Request:', url)
+      return fetch(url, init)
+    }
+    return next({ fetch: customFetch })
+  },
+)
+```
+
+Fetch precedence (highest to lowest): call site → later middleware → earlier middleware → createStart global → default fetch.
+
+## Common Mistakes
+
+### 1. HIGH: Trusting client sendContext without validation
+
+```tsx
+// WRONG — client can send arbitrary data
+.server(async ({ next, context }) => {
+  await db.query(`SELECT * FROM workspace_${context.workspaceId}`)
+  return next()
+})
+
+// CORRECT — validate before use
+.server(async ({ next, context }) => {
+  const workspaceId = z.string().uuid().parse(context.workspaceId)
+  await db.query('SELECT * FROM workspaces WHERE id = $1', [workspaceId])
+  return next()
+})
+```
+
+### 2. MEDIUM: Confusing request vs server function middleware
+
+Request middleware runs on ALL requests (SSR, routes, functions). Server function middleware runs only for `createServerFn` calls and has `.client()` method.
+
+### 3. HIGH: Browser APIs in .client() crash during SSR
+
+During SSR, `.client()` callbacks run on the server. Browser-only APIs like `localStorage` or `window` will throw `ReferenceError`:
+
+```tsx
+// WRONG — localStorage doesn't exist on the server during SSR
+const middleware = createMiddleware({ type: 'function' }).client(
+  async ({ next }) => {
+    const token = localStorage.getItem('token')
+    return next({ sendContext: { token } })
+  },
+)
+
+// CORRECT — use cookies/headers or guard with typeof window check
+const middleware = createMiddleware({ type: 'function' }).client(
+  async ({ next }) => {
+    const token =
+      typeof window !== 'undefined' ? localStorage.getItem('token') : null
+    return next({ sendContext: { token } })
+  },
+)
+```
+
+### 4. MEDIUM: Wrong method order
+
+```tsx
+// WRONG — type error
+createMiddleware({ type: 'function' })
+  .server(() => { ... })
+  .client(() => { ... })
+
+// CORRECT — middleware → inputValidator → client → server
+createMiddleware({ type: 'function' })
+  .middleware([dep])
+  .inputValidator(schema)
+  .client(({ next }) => next())
+  .server(({ next }) => next())
+```
+
+## Cross-References
+
+- [start-core/server-functions](../server-functions/SKILL.md) — what middleware wraps
+- [start-core/server-routes](../server-routes/SKILL.md) — middleware on API endpoints

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 '@benjavicente/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 '@benjavicente/react-router'
+import { createServerFn } from '@benjavicente/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 '@benjavicente/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 '@benjavicente/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 '@benjavicente/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 '@benjavicente/react-start'
+import {
+  getRequest,
+  getRequestHeader,
+  setResponseHeaders,
+  setResponseStatus,
+} from '@benjavicente/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 '@benjavicente/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