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

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

Скилл route-handlers помогает ИИ-агенту писать API-роуты для Next.js App Router: от стандартных эндпоинтов до потоковой передачи данных и настройки CORS.

MIT 152 установок ★ 3 785 обновлён 2026-10-25

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

Что делает route-handlers

Скилл объясняет агенту архитектуру Route Handlers внутри каталога app/ в файлах route.ts. Он содержит готовые структуры под HTTP-методы GET, POST, PUT, PATCH, DELETE, HEAD и OPTIONS, а также правила разбора JSON, FormData и обычного текста из входящих запросов.

Внутрь заложены паттерны для работы с cookies через cookies() из next/headers, валидации Bearer-токенов в заголовках, конфигурации CORS и управления кэшированием с помощью export const dynamic = 'force-dynamic'. Для работы с языковыми моделями приведены шаблоны потоковой отдачи текста через ReadableStream и Server-Sent Events.

Все паттерны завязаны на структуру App Router. Если проект написан на старом Pages Router с папкой pages/api, этот скилл выдаст несовместимый код.

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

  • написать эндпоинт в app/api/.../route.ts под нужный HTTP-метод
  • настроить потоковую выдачу ответов нейросетей через ReadableStream
  • разобрать динамические параметры маршрута и searchParams в URL
  • выставить cookie сессии или заголовки CORS штатными средствами Next.js

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

  • Создай роут app/api/posts/[id]/route.ts с методами GET и DELETE
  • Настрой стриминг ответа нейросети через ReadableStream в route handler
  • Добавь проверку Bearer-токена в заголовках для эндпоинта пользователей

Как установить route-handlers

1Через Skills CLI (Vercel)

npx skills add davepoon/buildwithclaude --skill route-handlers -a claude-code

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

~/.claude/skills/route-handlers/SKILL.md

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

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

Вопросы о route-handlers

Как установить route-handlers в Claude Code?

Выполните команду npx skills add davepoon/buildwithclaude --skill route-handlers -a claude-code. Скилл запишется в ~/.claude/skills/route-handlers/SKILL.md.

Что делает скилл route-handlers?

Он предоставляет агенту правила и примеры кода для написания API в Next.js App Router с использованием Web Request и Response API.

Подходит ли этот скилл для Pages Router?

Нет. Примеры и соглашения скилла рассчитаны только на файлы route.ts внутри каталога app.

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

SKILL.md · MIT
---
name: route-handlers
description: This skill should be used when the user asks to "create an API route", "add an endpoint", "build a REST API", "handle POST requests", "create route handlers", "stream responses", or needs guidance on Next.js API development in the App Router.
version: 1.0.0
---

# Next.js Route Handlers

## Overview

Route Handlers allow you to create API endpoints using the Web Request and Response APIs. They're defined in `route.ts` files within the `app` directory.

## Basic Structure

### File Convention

Route handlers use `route.ts` (or `route.js`):

```
app/
├── api/
│   ├── users/
│   │   └── route.ts      # /api/users
│   └── posts/
│       ├── route.ts      # /api/posts
│       └── [id]/
│           └── route.ts  # /api/posts/:id
```

### HTTP Methods

Export functions named after HTTP methods:

```tsx
// app/api/users/route.ts
import { NextResponse } from 'next/server'

export async function GET() {
  const users = await db.user.findMany()
  return NextResponse.json(users)
}

export async function POST(request: Request) {
  const body = await request.json()
  const user = await db.user.create({ data: body })
  return NextResponse.json(user, { status: 201 })
}
```

Supported methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`

## Request Handling

### Reading Request Body

```tsx
export async function POST(request: Request) {
  // JSON body
  const json = await request.json()

  // Form data
  const formData = await request.formData()
  const name = formData.get('name')

  // Text body
  const text = await request.text()

  return NextResponse.json({ received: true })
}
```

### URL Parameters

Dynamic route parameters:

```tsx
// app/api/posts/[id]/route.ts
interface RouteContext {
  params: Promise<{ id: string }>
}

export async function GET(
  request: Request,
  context: RouteContext
) {
  const { id } = await context.params
  const post = await db.post.findUnique({ where: { id } })

  if (!post) {
    return NextResponse.json(
      { error: 'Not found' },
      { status: 404 }
    )
  }

  return NextResponse.json(post)
}
```

### Query Parameters

```tsx
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const page = searchParams.get('page') ?? '1'
  const limit = searchParams.get('limit') ?? '10'

  const posts = await db.post.findMany({
    skip: (parseInt(page) - 1) * parseInt(limit),
    take: parseInt(limit),
  })

  return NextResponse.json(posts)
}
```

### Request Headers

```tsx
export async function GET(request: Request) {
  const authHeader = request.headers.get('authorization')

  if (!authHeader?.startsWith('Bearer ')) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    )
  }

  const token = authHeader.split(' ')[1]
  // Validate token...

  return NextResponse.json({ authenticated: true })
}
```

## Response Handling

### JSON Response

```tsx
import { NextResponse } from 'next/server'

export async function GET() {
  return NextResponse.json(
    { message: 'Hello' },
    { status: 200 }
  )
}
```

### Setting Headers

```tsx
export async function GET() {
  return NextResponse.json(
    { data: 'value' },
    {
      headers: {
        'Cache-Control': 'max-age=3600',
        'X-Custom-Header': 'custom-value',
      },
    }
  )
}
```

### Setting Cookies

```tsx
import { cookies } from 'next/headers'

export async function POST(request: Request) {
  const cookieStore = await cookies()

  // Set cookie
  cookieStore.set('session', 'abc123', {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    maxAge: 60 * 60 * 24 * 7, // 1 week
  })

  return NextResponse.json({ success: true })
}
```

### Redirects

```tsx
import { redirect } from 'next/navigation'
import { NextResponse } from 'next/server'

export async function GET() {
  // Option 1: redirect function (throws)
  redirect('/login')

  // Option 2: NextResponse.redirect
  return NextResponse.redirect(new URL('/login', request.url))
}
```

## Streaming Responses

### Text Streaming

```tsx
export async function GET() {
  const encoder = new TextEncoder()
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 10; i++) {
        controller.enqueue(encoder.encode(`data: ${i}\n\n`))
        await new Promise(resolve => setTimeout(resolve, 100))
      }
      controller.close()
    },
  })

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    },
  })
}
```

### AI/LLM Streaming

```tsx
export async function POST(request: Request) {
  const { prompt } = await request.json()

  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: prompt }],
    stream: true,
  })

  const stream = new ReadableStream({
    async start(controller) {
      for await (const chunk of response) {
        const text = chunk.choices[0]?.delta?.content || ''
        controller.enqueue(new TextEncoder().encode(text))
      }
      controller.close()
    },
  })

  return new Response(stream, {
    headers: { 'Content-Type': 'text/plain' },
  })
}
```

## CORS Configuration

```tsx
export async function OPTIONS() {
  return new Response(null, {
    status: 204,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  })
}

export async function GET() {
  return NextResponse.json(
    { data: 'value' },
    {
      headers: {
        'Access-Control-Allow-Origin': '*',
      },
    }
  )
}
```

## Caching

### Static (Default for GET)

```tsx
// Cached by default
export async function GET() {
  const data = await fetch('https://api.example.com/data')
  return NextResponse.json(await data.json())
}
```

### Opt-out of Caching

```tsx
export const dynamic = 'force-dynamic'

export async function GET() {
  // Always fresh
}

// Or use cookies/headers (auto opts out)
import { cookies } from 'next/headers'

export async function GET() {
  const cookieStore = await cookies()
  // Now dynamic
}
```

## Error Handling

```tsx
export async function GET(request: Request) {
  try {
    const data = await riskyOperation()
    return NextResponse.json(data)
  } catch (error) {
    console.error('API Error:', error)

    if (error instanceof ValidationError) {
      return NextResponse.json(
        { error: error.message },
        { status: 400 }
      )
    }

    return NextResponse.json(
      { error: 'Internal Server Error' },
      { status: 500 }
    )
  }
}
```

## Resources

For detailed patterns, see:
- `references/http-methods.md` - Complete HTTP method guide
- `references/streaming-responses.md` - Advanced streaming patterns
- `examples/crud-api.md` - Full CRUD API example

© davepoon · MIT · davepoon/buildwithclaude

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

Все скиллы по теме «Бэкенд и API» →
nextjs-cache-architecture mohamed-hossam1 Скилл nextjs-cache-architecture выстраивает архитектуру кеширования для Next.js 16+ App Router. Помогает внедрить директиву "use cache", собрать типизированный реестр тегов и настроить границы Suspense. CX Codex +1 5 100установок nextjs-app-router giuseppe-trisciuoglio Скилл nextjs-app-router для Claude Code помогает создавать приложения на Next.js 16+ с App Router. Подключается при работе с серверными компонентами, формами, API-маршрутами и кэшированием. CX Codex +1 4 100установок nextjs-best-practices davila7 Скилл nextjs-best-practices для Claude Code задаёт правила App Router: разделяет серверные и клиентские компоненты, настраивает кэширование и структуру маршрутов. CX Codex +1 1 785установок nextjs-server-client-components wsimmonds Скилл nextjs-server-client-components помогает выбрать между Server и Client Components в Next.js App Router, настроить чтение cookies, работу с searchParams и избежать смешивания клиентских и серверных API. CX Codex +1 364установок nextjs-advanced-routing wsimmonds Скилл nextjs-advanced-routing для Claude Code и пяти других платформ, который учит агента работать с App Router: Route Handlers, Server Actions, Parallel Routes, Intercepting Routes и Suspense. CX Codex +1 336установок nextjs-15 gentleman-programming Скилл задаёт паттерны работы с App Router в Next.js 15: маршрутизацию, Server Actions, параллельную загрузку данных и настройку middleware. CX Codex +1 185установок

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

Весь набор →
macos-design Скилл macos-design для Claude Code помогает проектировать интерфейсы macOS по системным паттернам, со светлой и тёмной темами. Задача — проектирование интерфейсов десктопных приложений и утилит. CX Codex +1 192установок auth-patterns Скилл auth-patterns для Claude Code собирает шаблоны аутентификации Next.js: настройку NextAuth.js v5, защиту маршрутов через middleware, RBAC и работу с сессиями в серверных компонентах. CX Codex +1 183установок server-components Скилл объясняет архитектуру React Server Components в Next.js: границы Server и Client Components, композицию и загрузку данных. CX Codex +1 158установок app-router Скилл для создания маршрутов, лейаутов, состояний загрузки и границ ошибок в Next.js App Router. Помогает агенту правильно организовать файловую структуру проекта. CX Codex +1 153установок canva-automation Скилл canva-automation управляет дизайнами, ассетами, папками и автозаполнением шаблонов в Canva через Rube MCP. CX Codex +1 149установок google-calendar-automation Скилл google-calendar-automation управляет событиями Google Calendar, ищет свободные интервалы и работает с участниками через Rube MCP. CX Codex +1 142установок outlook-automation Скилл outlook-automation для Claude Code автоматизирует работу с письмами, календарём, контактами и папками Outlook через Rube MCP. Ищет письма по условиям и управляет событиями и контактами. CX Codex +1 140установок tiktok-automation Скилл tiktok-automation автоматизирует выгрузку видео, публикацию фото и сбор статистики TikTok через Rube MCP и Composio прямо из диалога с агентом. CX Codex +1 140установок

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

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