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

server-routes — скилл для Claude Code: что делает и как установить

Скилл server-routes для Claude Code создаёт серверные API-маршруты в TanStack Router и разбирает HTTP-запросы. Эндпоинты размещаются рядом с маршрутами приложения.

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

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

Что делает server-routes

Скилл учит агента описывать API-маршруты через server в createFileRoute. Он работает с обработчиками GET, POST, PUT и DELETE, параметрами пути, телом запроса и ответами с JSON, статусами и заголовками. Файлы маршрутов лежат в src/routes и следуют соглашениям TanStack Router.

Внутри есть примеры контекста обработчика с request, params, context, pathname и next. Агент также разбирает middleware для всех обработчиков и отдельного метода через createHandlers, а ещё сочетание серверного и UI-маршрута в одном файле. Для работы скиллу нужен start-core.

SSR-loader не должен вызывать собственный серверный маршрут через fetch: общую операцию следует вынести в серверный сервис и подключить к обеим границам. Это ограничение влияет на структуру приложения.

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

  • создать API-маршрут рядом с файлом приложения
  • разобрать JSON-тело POST-запроса
  • добавить параметры динамического пути
  • вернуть JSON с нужным статусом
  • подключить middleware только к одному HTTP-методу

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

  • Создай серверный маршрут src/routes/api/users.ts с обработчиками GET и POST.
  • Добавь к POST в src/routes/api/posts.ts проверку через middleware, а к GET оставь общий обработчик.
  • Покажи, как получить params.id и вернуть ответ 404, если пользователь не найден.

Как установить server-routes

1Через Skills CLI (Vercel)

npx skills add TanStack/router --skill server-routes -a claude-code

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

~/.claude/skills/server-routes/SKILL.md

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

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

Вопросы о server-routes

Как установить server-routes в Claude Code?

Выполните npx skills add TanStack/router --skill server-routes -a claude-code. Затем проверьте файл ~/.claude/skills/server-routes/SKILL.md.

Что делает server-routes?

Скилл помогает создавать серверные API-маршруты через createFileRoute, настраивать HTTP-обработчики и читать контекст запроса. Он также объясняет middleware и соглашения имён файлов.

Нужен ли для server-routes отдельный компонент TanStack?

Для работы скиллу нужен start-core. Серверные маршруты подходят для HTTP-контракта, а данные только для приложения лучше получать через серверную функцию.

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

SKILL.md · MIT
---
name: 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.
metadata:
  type: sub-skill
  library: tanstack-start
  library_version: '1.170.14'
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.

Use server routes when callers need an HTTP contract. For data used only by the Start application, prefer a server function and call it directly from the loader. A route loader runs during SSR and client navigation, so `fetch('/api/...')` is not a portable loader pattern.

## 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>
  )
}
```

The relative `fetch('/hello')` above is safe because it runs only in a browser click handler.

## Sharing Data with a Start Route

Do not make the SSR loader call its own server route. Put the business operation in a server-only service, then expose it through both boundaries when both are required:

```tsx
// src/server/issues.server.ts
export function listIssues() {
  return db.issues.findMany()
}

// src/routes/api/issues.ts
export const Route = createFileRoute('/api/issues')({
  server: {
    handlers: {
      GET: async () => Response.json(await listIssues()),
    },
  },
})

// src/routes/issues.tsx
const getIssues = createServerFn({ method: 'GET' }).handler(() => {
  return listIssues()
})

export const Route = createFileRoute('/issues')({
  loader: () => getIssues(),
})
```

This keeps SSR independent of URL resolution and keeps one source of business logic.

## 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. CRITICAL: Protecting the page but not the server route

Every handler that reads or writes private data must authenticate and authorize the request through route middleware, handler middleware, or an in-handler check. A router `beforeLoad` redirect does not protect `/api/...`. Test the handler directly without cookies and assert that no private payload is returned.

### 2. 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
```

### 3. 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()
```

### 4. HIGH: Trusting TypeScript as response-schema validation

Validate request input and test the serialized `Response` output. A typed service can still be projected or serialized without a newly added field. For schema changes, assert `await response.json()` at the server-route boundary.

## 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

© TanStack · MIT · TanStack/router

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

Все скиллы по теме «Бэкенд и API» →
vtex-io-http-routes vtex Скилл vtex-io-http-routes помогает проектировать HTTP-эндпоинты бэкенд-сервиса VTEX IO: границы роутов, middleware, валидацию запросов и форму ответа. CX Codex +1 1 200установок Cross-Chain Bridge Routes — 60+ Chains via LI.FI axel-belfort Cross-Chain Bridge Routes — 60+ Chains via LI.FI — MCP-сервер для Claude Code: сравнивает маршруты перевода токенов между 60+ блокчейнами и показывает комиссии, время и рейтинг безопасности до перевода. CX Codex +1 3 748установок expo-api-routes официальный Expo Team Скилл expo-api-routes для Codex объясняет, как писать серверные API-роуты в Expo Router и выкладывать их на EAS Hosting. Держит ключи и запросы к базе на сервере, не на клиенте. CX Codex GP ChatGPT +1 1установок async-api-routes tech-leads-club Правило async-api-routes устраняет цепочки водопадов в обработчиках API и Server Actions. Оно запускает независимые асинхронные вызовы сразу, не дожидаясь завершения других промисов. CX Codex +1 ★ 7 191звёзд репо nextjs-dynamic-routes-params wsimmonds Скилл nextjs-dynamic-routes-params для Claude Code строит динамические сегменты App Router и читает params в Next.js 15+. Покрывает маршруты по ID или слагу. CX Codex +1 304установок tanstack-start-cursorrules-prompt-file PatrickJS Правило tanstack-start-cursorrules-prompt-file для Cursor описывает структуру TanStack Start и типобезопасную разработку с SSR. Активируется в проектах Start, маршрутах TanStack Router и конфигурации Vinxi. CX Codex +1 ★ 41 178звёзд репо

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

Весь набор →
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установок middleware Учит работать с middleware-цепочками TanStack Start. Покрывает createMiddleware, передачу контекста через next(), sendContext и глобальные хуки через src/start.ts. CX Codex +1 206установок 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установок bundle-size-optimization Скилл bundle-size-optimization для Claude Code измеряет клиентские бандлы TanStack Router и сравнивает кандидатов с сохранённым базовым замером. Проверяет, вырос ли gzip после правки. CX Codex +1 139установок

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

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