route-handlers — Claude Code skill: what it does, how to install
route-handlers guides coding agents in building Next.js App Router API routes, parsing incoming payloads, and streaming LLM responses.
MIT 152 installs ★ 3,785 updated 2026-10-25
npx skills add davepoon/buildwithclaude --skill route-handlers -a claude-codeWhat route-handlers does
The skill provides guidelines and TypeScript templates for building route handlers inside route.ts files within the app directory. It covers standard HTTP method exports including GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS, showing how to read JSON, FormData, or raw text payloads.
It outlines patterns for reading route contexts, parsing search parameters, setting session cookies via next/headers, and configuring CORS headers. It also includes boilerplate for Server-Sent Events and streaming AI responses with ReadableStream.
The templates strictly require the Next.js App Router. They will not work in legacy projects using pages/api.
What it helps with
- build API endpoints in Next.js App Router using
route.ts - stream LLM completions using
ReadableStreamand SSE - extract route params and search queries from dynamic URLs
- manage session cookies and CORS headers with standard Web APIs
Example prompts for the agent
- Create a POST route in
app/api/users/route.tsthat validates JSON body - Set up an LLM streaming route handler using ReadableStream
- Add Bearer authorization checks to my route handler
How to install route-handlers
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill route-handlers -a claude-code2Manually: put the files in place
~/.claude/skills/route-handlers/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/route-handlers/
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill route-handlers -a codex2Manually: put the files in place
.agents/skills/route-handlers/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill route-handlers -a cursor2Manually: put the files in place
.cursor/skills/route-handlers/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install davepoon/buildwithclaude plugins/nextjs-expert/skills/route-handlers2Manually: put the files in place
.github/skills/route-handlers/SKILL.md1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill route-handlers -a gemini-cli2Platform CLI
gemini skills install https://github.com/davepoon/buildwithclaude --path plugins/nextjs-expert/skills/route-handlersManually: put the files in place
.devin/skills/route-handlers/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill route-handlers -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about route-handlers
How do I install route-handlers in Claude Code?
Run npx skills add davepoon/buildwithclaude --skill route-handlers -a claude-code. The instructions will be saved to ~/.claude/skills/route-handlers/SKILL.md.
What does route-handlers do?
It gives the model reference patterns for building Next.js App Router API endpoints using the standard Request and Response APIs.
Does route-handlers work with the Pages Router?
No. The skill specifically targets route.ts files inside the Next.js app folder.
Source text
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