К основному содержанию
скилл CX Codex

middleware — скилл TanStack Start для Claude Code и Codex

Скилл для Claude Code, Codex, Cursor и других агентов учит работать с middleware-цепочками TanStack Start. Покрывает createMiddleware, передачу контекста через next(), sendContext и глобальные хуки через src/start.ts.

MIT 206 установок ★ 15 341 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add TanStack/router --skill middleware -a claude-code
Открыть на GitHub

Что делает middleware

Скилл добавляет в контекст агента документацию по двум типам middleware TanStack Start: request middleware (только .server(), перехватывает все серверные запросы) и server function middleware (.client() + .server(), работает только на серверных функциях).

Внутри — описание createMiddleware и createMiddleware({ type: 'function' }), способы передачи данных через next({ context }) и sendContext, подключение к серверным маршрутам через createFileRoute, глобальная регистрация через createStart в src/start.ts. TypeScript принудительно требует порядок методов: middleware() → validator() → client() → server(), нарушение порядка вызывает ошибки типов.

Важный момент про sendContext: валидация формы идентификатора с помощью Zod не означает авторизацию. Любой ID, пришедший с клиента, нужно проверять по сессии перед использованием как ключа запроса или параметра фильтра. Скилл требует установленных зависимостей start-core и start-core/server-functions.

Какие задачи решает

  • добавить логирование всех входящих серверных запросов через request middleware
  • передать данные сессии по цепочке middleware без лишних запросов к базе
  • отправить контекст с клиента на сервер через sendContext и получить его обратно
  • зарегистрировать глобальный auth-middleware для всех серверных функций
  • прикрепить middleware только к конкретному HTTP-методу в createFileRoute

Примеры запросов агенту

  • Напиши request middleware для логирования метода и URL каждого запроса
  • Создай цепочку middleware: сначала auth проверяет сессию, потом role получает роль из контекста
  • Добавь в src/start.ts глобальный middleware через createStart

Как установить middleware

1Через Skills CLI (Vercel)

npx skills add TanStack/router --skill middleware -a claude-code

2Вручную: положить файлы

~/.claude/skills/middleware/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/middleware/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о middleware

Как установить скилл middleware в Claude Code?

Выполните в терминале npx skills add TanStack/router --skill middleware -a claude-code. Скилл появится по пути ~/.claude/skills/middleware/SKILL.md.

Чем отличается request middleware от server function middleware?

Request middleware перехватывает все серверные запросы (SSR, маршруты, функции) и работает только в .server(). Server function middleware работает только на серверных функциях, но имеет фазы .client() и .server(), поддерживает валидацию через .validator() и двустороннюю передачу контекста.

Нужно ли что-то установить до скилла?

Скилл требует start-core и start-core/server-functions — их нужно подключить первыми.

Исходный текст

SKILL.md · MIT
---
name: 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.
metadata:
  type: sub-skill
  library: tanstack-start
  library_version: '1.170.14'
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()` → `validator()` → `client()` → `server()`. Wrong order causes type errors.
> **CRITICAL**: Validating the _shape_ of `sendContext` (e.g. `z.string().uuid().parse(...)`) is NOT authorization. A parsed identifier is a well-formed identifier, not an authorized one. Always re-check access against the session principal before using a client-sent ID as a query key, filter, or path parameter.

## 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 (`.validator()`)                     |
| 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 '@tanstack/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 '@tanstack/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 '@tanstack/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 '@tanstack/zod-adapter'

const workspaceMiddleware = createMiddleware({ type: 'function' })
  .validator(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 '@tanstack/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 } })
})
```

> **Attach `authMiddleware` to every `createServerFn` that needs auth.** Server functions are API endpoints; a route `beforeLoad` does not protect their data, only the route's UI. Protect the endpoint that reads or mutates private data. See `@tanstack/router-core#router-core/auth-and-guards` and [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md).

```tsx
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 '@tanstack/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. CRITICAL: Trusting client sendContext — shape check is not access check

`sendContext` from a client middleware arrives on the server as untrusted client input. Most agents stop after parsing the shape with Zod and assume the value is safe. It isn't: a parsed UUID is _some_ workspace, not the requesting user's workspace. Without a membership check against the session principal, you've built a tenant-walking endpoint.

**Layer 1 — WRONG (no validation):**

```tsx
.server(async ({ next, context }) => {
  // SQL-injectable AND tenant-walkable
  await db.query(`SELECT * FROM workspace_${context.workspaceId}`)
  return next()
})
```

**Layer 2 — STILL WRONG (shape only):**

```tsx
.server(async ({ next, context }) => {
  // Looks safe, isn't. UUID is well-formed but the user may not be a member.
  const workspaceId = z.string().uuid().parse(context.workspaceId)
  await db.query('SELECT * FROM workspaces WHERE id = $1', [workspaceId])
  return next()
})
```

**Layer 3 — CORRECT (shape AND access):**

```tsx
.middleware([authMiddleware]) // session loaded from cookie, NOT from sendContext
.server(async ({ next, context }) => {
  const workspaceId = z.string().uuid().parse(context.workspaceId)
  // Verify the session principal can access this workspace.
  const member = await db.memberships.find({
    userId: context.session.userId,
    workspaceId,
  })
  if (!member) throw new Error('Not a member of this workspace')
  await db.query('SELECT * FROM workspaces WHERE id = $1', [workspaceId])
  return next({ context: { workspaceId } })
})
```

The session itself must come from a server-trusted source (the cookie + DB lookup in `authMiddleware`), never from `sendContext` — anything the client can send, the client can lie about. See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md).

### 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 → validator → client → server
createMiddleware({ type: 'function' })
  .middleware([dep])
  .validator(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
- [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) — building the `authMiddleware` factory itself: session cookie reads, OAuth state, CSRF
- `@tanstack/router-core#router-core/auth-and-guards` — routing-side UX guards; data auth belongs in the server function, server route, or API endpoint handler/middleware

© TanStack · MIT · TanStack/router

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
tanstack-start-cursorrules-prompt-file PatrickJS Правило tanstack-start-cursorrules-prompt-file для Cursor описывает структуру TanStack Start и типобезопасную разработку с SSR. Активируется в проектах Start, маршрутах TanStack Router и конфигурации Vinxi. CX Codex +1 ★ 41 178звёзд репо hono-middleware bobmatnyc Скилл hono-middleware для Claude Code и других платформ: паттерны middleware для Hono — создание, композиция, встроенные модули и порядок выполнения. Покрывает авторизацию, CORS и логирование. CX Codex +1 452установок tanstack-vue-router-skilld skilld-dev Скилл tanstack-vue-router-skilld для работы с @tanstack/vue-router — типобезопасным роутером Vue. Учит агента правилам настройки, file-based маршрутов, композаблов с Ref, линков и лоадеров. CX Codex +1 101установок tanstack-vue-form-skilld skilld-dev Скилл tanstack-vue-form-skilld помогает писать, проверять и отлаживать формы Vue на @tanstack/vue-form с актуальным API TanStack Form. CX Codex +1 125установок safe-action-middleware next-safe-action Скилл safe-action-middleware объясняет, как писать middleware для next-safe-action: аутентификация, авторизация, логирование, лимиты и расширение контекста. CX Codex +1 1 200установок base44-platform-agents base44 Скилл base44-platform-agents для Claude Code помогает создавать ИИ-агентов внутри приложений Base44. Он включается при работе над разговорным помощником или программируемым ИИ. CX Codex +1 3 000установок

Из того же набора25

Весь набор →
code-splitting Скилл code-splitting разделяет код маршрутов TanStack Router на критичную и ленивую части: автоматически создаёт отдельные чанки или позволяет настроить разделение вручную. CX Codex +1 212установок not-found-and-errors Скилл not-found-and-errors обучает агента настраивать экраны 404 и обработку ошибок в TanStack Router. Помогает пробросить notFound() из loader и оформить запасной UI. CX Codex +1 211установок deployment Скилл deployment разворачивает приложения TanStack Start на Cloudflare Workers, Netlify, Vercel, Node.js, Bun и Railway. Управляет SSR по маршрутам, статическим пререндерингом и SEO. CX Codex +1 210установок path-params Скилл path-params для работы с динамическими параметрами в URL-адресах маршрутов TanStack Router. Позволяет захватывать переменные части пути, настраивать опциональные сегменты и создавать шаблоны с префиксами и суффиксами. CX Codex +1 208установок server-routes Скилл server-routes для Claude Code создаёт серверные API-маршруты в TanStack Router и разбирает HTTP-запросы. Эндпоинты размещаются рядом с маршрутами приложения. CX Codex +1 205установок ssr Скилл ssr помогает настроить серверный рендеринг в TanStack Router: потоковый или обычный. Пригодится при интеграции роутера с существующим сервером. CX Codex +1 202установок auth-server-primitives Скилл auth-server-primitives для Claude Code помогает собрать серверную часть аутентификации в TanStack Start. Он включается при работе с сессиями, OAuth, сбросом пароля и защитой серверных функций. CX Codex +1 201установок migrate-from-react-router Скилл migrate-from-react-router для Claude Code ведёт по шагам переезда с React Router v7 на TanStack Router: от конвертации маршрутов до навигации и search-параметров. CX Codex +1 188установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой