Next Route Handlers

# Next.js Route Handlers

> Create HTTP endpoints in the App Router using route.ts with typed method exports

## When to Use

- Building REST API endpoints for external consumers or third-party webhooks
- Handling non-mutation requests (GET, HEAD) that should not be Server Actions
- Processing webhook payloads (Stripe, GitHub, CMS) with signature verification
- Implementing file downloads, streaming responses, or custom content types
- Bridging Next.js with external systems that cannot call Server Actions directly

## Instructions

1. Create `app/api/[resource]/route.ts` and export named async functions `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
2. Accept `(request: NextRequest)` as the first parameter — use `request.json()`, `request.text()`, or `request.formData()` to parse the body.
3. Return a `Response` or `NextResponse` — use `NextResponse.json(data, { status })` for JSON responses.
4. Access dynamic segments via the second parameter: `({ params }: { params: { id: string } })`.
5. Validate webhook signatures before processing — use `request.text()` to read the raw body (needed for HMAC verification), then parse JSON manually.
6. Set the `runtime` export to `'edge'` for global low-latency endpoints; omit it (defaults to Node.js) when you need Node.js APIs.
7. Add `export const dynamic = 'force-dynamic'` if a GET handler should never be cached (e.g., it reads cookies or returns live data).
8. Prefer Server Actions for mutations triggered by your own UI — Route Handlers are for external integrations.

```typescript
// app/api/posts/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const updateSchema = z.object({ title: z.string().min(1) });

export async function GET(_request: NextRequest, { params }: { params: { id: string } }) {
  const post = await db.post.findUnique({ where: { id: params.id } });
  if (!post) return NextResponse.json({ error: 'Not found' }, { status: 404 });
  return NextResponse.json(post);
}

export async function PATCH(request: NextRequest, { params }: { params: { id: string } }) {
  const body = await request.json();
  const parsed = updateSchema.safeParse(body);
  if (!parsed.success) {
    return NextResponse.json({ errors: parsed.error.flatten() }, { status: 422 });
  }
  const post = await db.post.update({ where: { id: params.id }, data: parsed.data });
  return NextResponse.json(post);
}
```

## Details

Route Handlers replace `pages/api/` routes in the App Router. They live at `app/api/**/route.ts` (or any nested location in `app/` that does not conflict with a `page.tsx`). A `route.ts` file and a `page.tsx` file cannot coexist in the same directory.

**Caching behavior:** GET Route Handlers are statically cached by default when they do not read dynamic data (`cookies()`, `headers()`, request body). Use `export const dynamic = 'force-dynamic'` or read from `request` to opt out of caching.

**Webhook pattern:** Stripe and GitHub require reading the raw request body for HMAC signature verification. Read with `await request.text()`, verify the signature, then `JSON.parse()` the body manually. Using `request.json()` first consumes the stream and makes raw body unavailable.

**Streaming responses:** Return a `ReadableStream` in the `Response` body for streaming endpoints. This pattern is common for AI streaming responses (OpenAI, Anthropic SDK).

**CORS:** Route Handlers need explicit CORS headers for cross-origin requests. Handle `OPTIONS` requests and set `Access-Control-Allow-*` headers in both the OPTIONS handler and the main method handlers.

**tRPC integration:** tRPC's Next.js adapter mounts a single Route Handler at `app/api/trpc/[trpc]/route.ts` and delegates all procedure calls through it.

## Source

https://nextjs.org/docs/app/building-your-application/routing/route-handlers

## Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

## Harness Integration

- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
- **No tools or state** — consumed as context by other skills and agents.

## Success Criteria

- The patterns described in this document are applied correctly in the implementation.
- Edge cases and anti-patterns listed in this document are avoided.