Frontend Beauty
ESC

Type to search the knowledge base.

Route Handlers

Route Handlers implement HTTP endpoints with route.ts: verbs, Request/Response, caching, and when to prefer Server Actions.

intermediate3 min read
  • nextjs
  • route-handlers

Route Handlers live in route.ts (or route.js) under app/ and export functions named after HTTP methods. They replace many pages/api use cases.

Docs: Route Handlers.

Basic GET/POST

// app/api/hello/route.ts
import { NextRequest } from 'next/server';

export async function GET() {
  return Response.json({ ok: true });
}

export async function POST(req: NextRequest) {
  const body = await req.json();
  return Response.json({ received: body }, { status: 201 });
}

Dynamic segments

// app/api/posts/[id]/route.ts
export async function GET(
  _req: Request,
  ctx: { params: Promise<{ id: string }> }
) {
  const { id } = await ctx.params;
  const post = await db.posts.get(id);
  if (!post) return new Response('Not found', { status: 404 });
  return Response.json(post);
}

When to use versus Server Actions

Use case Prefer
Form mutations from your UI Server Actions
Public HTTP API / webhooks Route Handlers
Third-party callbacks Route Handlers
Simple cookie redirects Middleware or handlers

Caching

GET handlers can be static if they do not use dynamic data. Export segment config or use fetch options carefully. Authenticated APIs are usually dynamic.

Interview out-loud

“Route Handlers export HTTP method functions from route.ts to build API endpoints in the App Router. I use them for webhooks and public HTTP APIs, and I prefer Server Actions for first-party form mutations that stay inside the Next app.”

Further reading

Edge cases worth rehearsing

Interviewers and production incidents cluster around the same edges: first render versus update, empty and loading states, Strict Mode double setup, concurrent interruptions, and what happens when identity (key, route params, user id) changes mid-edit. Walk one concrete user journey end-to-end — open, edit, navigate away, come back — and say which state survives.

Prefer fixing data flow and ownership before reaching for memoization or micro-optimizations. Prefer event handlers over effects when a user action is the trigger. Prefer deriving values during render over mirroring props into state. Prefer stable list keys from business ids. Measure with the profiler when performance is the claim.

When you cite an API, mention one failure mode: abort on unmount, serializable props across server/client boundaries, focus restoration for dialogs, or cache invalidation after a mutation. Specific beats generic every time.

Edge cases worth rehearsing

Interviewers and production incidents cluster around the same edges: first render versus update, empty and loading states, Strict Mode double setup, concurrent interruptions, and what happens when identity (key, route params, user id) changes mid-edit. Walk one concrete user journey end-to-end — open, edit, navigate away, come back — and say which state survives.

Prefer fixing data flow and ownership before reaching for memoization or micro-optimizations. Prefer event handlers over effects when a user action is the trigger. Prefer deriving values during render over mirroring props into state. Prefer stable list keys from business ids. Measure with the profiler when performance is the claim.

When you cite an API, mention one failure mode: abort on unmount, serializable props across server/client boundaries, focus restoration for dialogs, or cache invalidation after a mutation. Specific beats generic every time.

Related guides