server-routes — скилл для Claude Code: что делает и как установить
Скилл server-routes для Claude Code создаёт серверные API-маршруты в TanStack Router и разбирает HTTP-запросы. Эндпоинты размещаются рядом с маршрутами приложения.
MIT 205 установок ★ 15 341 обновлён 2026-10-25
npx skills add TanStack/router --skill server-routes -a claude-codeЧто делает 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-code2Вручную: положить файлы
~/.claude/skills/server-routes/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/server-routes/
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill server-routes -a codex2Вручную: положить файлы
.agents/skills/server-routes/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill server-routes -a cursor2Вручную: положить файлы
.cursor/skills/server-routes/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install TanStack/router packages/start-client-core/skills/start-core/server-routes2Вручную: положить файлы
.github/skills/server-routes/SKILL.md1Через Skills CLI (Vercel)
npx skills add TanStack/router --skill server-routes -a gemini-cli2Командой платформы
gemini skills install https://github.com/TanStack/router --path packages/start-client-core/skills/start-core/server-routesВручную: положить файлы
.devin/skills/server-routes/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add TanStack/router --skill server-routes -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в 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