fusengine/start-middleware

TanStack Start Middleware

Middleware customizes the behavior of server functions and server routes. It is composable — one middleware can depend on others to form an ordered chain. Import createMiddleware from @tanstack/react-start. This skill targets @tanstack/react-start v1.166.2.

Agent Workflow (MANDATORY)

Before implementing, verify current APIs against Context7 (/websites/tanstack_start_framework_react) + Exa, then explore the target codebase. After changes, run fuse-ai-pilot:sniper.

Critical Rules (read first)

1. TypeScript enforces method order: .middleware() → .validator() → .client() → .server(). Any other order is a type error.
2. Shape validation is NOT authorization. A parsed UUID from sendContext is a well-formed identifier, not an authorized one. Always re-check access against the session principal before using a client-sent value as a query key, filter, or path param.
3. Client context is not sent to the server by default. You must opt in with next({ sendContext }). Anything the client sends, the client can lie about — derive the session from a server-trusted source (cookie + DB), never from sendContext.
4. .client() runs on the server during SSR. Guard browser-only APIs (localStorage, window) with typeof window !== 'undefined'.
5. staticFunctionMiddleware must be LAST in the chain (from @tanstack/start-static-server-functions, experimental).

Overview

| Feature | Request Middleware | Server Function Middleware | |---------|--------------------|-----------------------------| | Created with | createMiddleware() | createMiddleware({ type: 'function' }) | | Scope | All server requests (SSR, routes, functions) | Server functions only | | Methods | .server() | .client(), .server() | | Input validation | No | Yes (.validator()) | | Client-side logic | No | Yes |

Request middleware cannot depend on server function middleware; server function middleware can depend on both.

Architecture

src/
├── start.ts              # createStart → global request/function middleware
├── middleware/
│   ├── auth.ts           # authMiddleware (request) + authorization factory
│   └── logging.ts        # request logging

→ See auth-authorization.md

Reference Guide

Concepts

| Topic | Reference | Load when | |-------|-----------|-----------| | Types & chaining | types.md | Choosing request vs function middleware, attaching to fns/routes | | Context passing | context.md | Sharing data via next(), sendContext client↔server, headers/fetch | | Global & static | global.md | Global middleware, execution order, staticFunctionMiddleware |

Templates

| Template | When to Use | |----------|-------------| | auth-authorization.md | Auth + permission-based authorization factory | | client-middleware.md | Client-side headers, custom fetch, telemetry |

Quick Reference

Request middleware

import { createMiddleware } from '@tanstack/react-start'

const logging = createMiddleware().server(async ({ next, request }) => {
  console.log(request.url)
  return next()
})

Server function middleware with context

const auth = createMiddleware().server(async ({ next, request }) => {
  const session = await getSession(request.headers)
  if (!session) throw new Error('Unauthorized')
  return next({ context: { session } }) // typed downstream
})

const fn = createServerFn().middleware([auth]).handler(async ({ context }) =>
  db.orders.findMany({ where: { userId: context.session.userId } }),
)

→ See context.md for sendContext and header merging

Best Practices

DO

• Load the session in a request middleware from a server-trusted cookie
• Re-check access (membership/role) before trusting any client-sent id
• Use a factory for parameterized authorization (permissions per function)
• Keep method chains in the enforced order

DON'T

• Trust sendContext shape as authorization
• Call localStorage/window in .client() without an SSR guard
• Place staticFunctionMiddleware anywhere but last