route.ts in Next.js — Building Custom APIs with Web Request and Response

Route Handlers in Next.js allow you to define custom request logic using Web APIs. With support for all major HTTP methods, cookies, headers, query parameters, dynamic segments, streaming, and webhooks, route.ts files offer a powerful way to build flexible, server-side functionality directly within your app.

route.tsNextRequestWeb APIStreamingWebhooks

1. What Is route.ts?

route.ts files in Next.js let you define custom request handlers for specific routes using the Web Request and Response APIs. These handlers run on the server and support all major HTTP methods.

2. Supported HTTP Methods

GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

export async function GET(request: Request) {}
export async function POST(request: Request) {}
export async function OPTIONS(request: Request) {}

3. Accessing Request Data

Use NextRequest to access cookies, headers, and query parameters:

import { type NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  const token = request.cookies.get('token')
  const referer = request.headers.get('referer')
  const query = request.nextUrl.searchParams.get('query')
}

4. Dynamic Route Parameters

Use params to access dynamic segments:

// app/items/[slug]/route.ts
export async function GET(request, { params }) {
  const { slug } = await params
}

5. Using RouteContext

For strong typing, use RouteContext:

export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) {
  const { id } = await ctx.params
  return Response.json({ id })
}

6. Cookies

Read and set cookies using cookies() from next/headers:

const cookieStore = await cookies()
cookieStore.set('token', 'abc123')

7. Headers

Read headers with headers() or request.headers. To set headers, return a new Response:

return new Response('Hello', {
  headers: { 'X-Custom': 'value' },
})

8. Reading Request Body

const json = await request.json()
const formData = await request.formData()

9. Query Parameters

const query = request.nextUrl.searchParams.get('query')

10. Revalidating Cached Data

export const revalidate = 60

11. Redirects

import { redirect } from 'next/navigation'
redirect('https://nextjs.org/')

12. Streaming Responses

Use ReadableStream or AI SDK for streaming content:

async function* makeIterator() {
  yield encoder.encode('<p>One</p>')
  await sleep(200)
  yield encoder.encode('<p>Two</p>')
}

const stream = iteratorToStream(makeIterator())
return new Response(stream)

13. CORS Headers

return new Response('Hello', {
  headers: {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Methods': 'GET, POST',
    'Access-Control-Allow-Headers': 'Content-Type',
  },
})

14. Webhooks

export async function POST(request: Request) {
  const payload = await request.text()
  return new Response('Success!', { status: 200 })
}

15. Non-UI Responses

Serve XML, icons, or metadata directly:

// app/rss.xml/route.ts
return new Response(`<rss>...</rss>`, {
  headers: { 'Content-Type': 'text/xml' },
})

Conclusion

route.ts in Next.js gives you full control over server-side logic. Whether you're building APIs, handling cookies, streaming data, or responding to webhooks, Route Handlers offer a clean and powerful way to extend your app’s backend capabilities.