Route Handlers

// app/api/hello/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  const name = request.nextUrl.searchParams.get("name") ?? "World";
  return NextResponse.json({ message: `Hello, ${name}` });
}

export async function POST(request: NextRequest) {
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return NextResponse.json({ error: "body must be valid JSON" }, { status: 400 });
  }
  const { name, age } = body as { name?: unknown; age?: unknown };
  if (typeof name !== "string") {
    return NextResponse.json({ error: "name is required" }, { status: 400 });
  }
  if (typeof age !== "number") {
    return NextResponse.json({ error: "age must be a number" }, { status: 400 });
  }
  return NextResponse.json({ message: `Hello, ${name}`, age }, { status: 201 });
}

$ docker run --rm -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 -e NPM_CONFIG_UPDATE_NOTIFIER=false node:26.13 npx next build 2>&1 | grep -v -E "Generating static pages using|Collecting page data using|Finished filesystem cache database compaction"
▲ Next.js 16.4.3 (Turbopack)
✓ Running next.config.ts took 75ms
- Cache Components enabled
- Partial Prefetching enabled

  Creating an optimized production build ...
✓ Compiled successfully in 2.3s
  Running TypeScript ...
  Finished TypeScript in 2.4s ...
  Finalizing page optimization ...

Route (app)
┌ ○ /
├ ○ /_not-found
└ ƒ /api/hello


○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand
$ docker run -d --name nextjs-route-handlers-6 -p 3100:3000 -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 node:26.13 npx next start
97264ddfb89311c510b4a588a4c453e00baa99c2a70efa95976218b8fb48df9a
$ until curl -s -o /dev/null http://localhost:3100/; do sleep 0.3; done
$ curl -s -i -X POST -H "Content-Type: application/json" -d '{"name":"Ada"}' http://localhost:3100/api/hello
HTTP/1.1 400 Bad Request
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
content-type: application/json
Date: Wed, 04 Nov 2026 07:19:12 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked

{"error":"age must be a number"}
$ curl -s -i -X POST -H "Content-Type: application/json" -d '{"name":"Ada","age":36}' http://localhost:3100/api/hello
HTTP/1.1 201 Created
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
content-type: application/json
Date: Wed, 04 Nov 2026 07:19:12 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked

{"message":"Hello, Ada","age":36}
$ docker rm -f nextjs-route-handlers-6
nextjs-route-handlers-6

age missing fails with its own message, separate from the name check; sending both fields succeeds and echoes age back as a real JSON number, not a string.

// app/api/hello/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  const name = request.nextUrl.searchParams.get("name") ?? "World";
  if (name.length > 20) {
    return NextResponse.json({ error: "name is too long" }, { status: 400 });
  }
  return NextResponse.json({ message: `Hello, ${name}` });
}

export async function POST(request: NextRequest) {
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return NextResponse.json({ error: "body must be valid JSON" }, { status: 400 });
  }
  const { name, age } = body as { name?: unknown; age?: unknown };
  if (typeof name !== "string") {
    return NextResponse.json({ error: "name is required" }, { status: 400 });
  }
  if (typeof age !== "number") {
    return NextResponse.json({ error: "age must be a number" }, { status: 400 });
  }
  return NextResponse.json({ message: `Hello, ${name}`, age }, { status: 201 });
}

$ docker run --rm -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 -e NPM_CONFIG_UPDATE_NOTIFIER=false node:26.13 npx next build 2>&1 | grep -v -E "Generating static pages using|Collecting page data using|Finished filesystem cache database compaction"
▲ Next.js 16.4.3 (Turbopack)
✓ Running next.config.ts took 72ms
- Cache Components enabled
- Partial Prefetching enabled

  Creating an optimized production build ...
✓ Compiled successfully in 2.7s
  Running TypeScript ...
  Finished TypeScript in 2.8s ...
  Finalizing page optimization ...

Route (app)
┌ ○ /
├ ○ /_not-found
└ ƒ /api/hello


○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand
$ docker run -d --name nextjs-route-handlers-7 -p 3100:3000 -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 node:26.13 npx next start
c97204ad7f9f7712da8fe404e9736804fc01f6601af0479b3b6e9cfe3c8f8a25
$ until curl -s -o /dev/null http://localhost:3100/; do sleep 0.3; done
$ curl -s -i "http://localhost:3100/api/hello?name=Ada"
HTTP/1.1 200 OK
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
content-type: application/json
Date: Wed, 04 Nov 2026 07:19:32 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked

{"message":"Hello, Ada"}
$ curl -s -i "http://localhost:3100/api/hello?name=ThisNameIsWayTooLongForTheLimit"
HTTP/1.1 400 Bad Request
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
content-type: application/json
Date: Wed, 04 Nov 2026 07:19:33 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked

{"error":"name is too long"}
$ docker rm -f nextjs-route-handlers-7
nextjs-route-handlers-7

Ada is 3 characters and passes through unchanged; the 31-character name trips the new check and gets 400 with {"error":"name is too long"} instead of ever reaching the NextResponse.json({ message: ... }) line.

// app/api/hello/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  const name = request.nextUrl.searchParams.get("name") ?? "World";
  if (name.length > 20) {
    return NextResponse.json({ error: "name is too long" }, { status: 400 });
  }
  return NextResponse.json({ message: `Hello, ${name}` });
}

export async function POST(request: NextRequest) {
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return NextResponse.json({ error: "body must be valid JSON" }, { status: 400 });
  }
  const { name, age } = body as { name?: unknown; age?: unknown };
  if (typeof name !== "string") {
    return NextResponse.json({ error: "name is required" }, { status: 400 });
  }
  if (typeof age !== "number") {
    return NextResponse.json({ error: "age must be a number" }, { status: 400 });
  }
  return NextResponse.json({ message: `Hello, ${name}`, age }, { status: 201 });
}

export async function PUT(request: NextRequest) {
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return NextResponse.json({ error: "body must be valid JSON" }, { status: 400 });
  }
  const { name } = body as { name?: unknown };
  if (typeof name !== "string") {
    return NextResponse.json({ error: "name is required" }, { status: 400 });
  }
  return NextResponse.json({ message: `Updated: ${name}` });
}

$ docker run --rm -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 -e NPM_CONFIG_UPDATE_NOTIFIER=false node:26.13 npx next build 2>&1 | grep -v -E "Generating static pages using|Collecting page data using|Finished filesystem cache database compaction"
▲ Next.js 16.4.3 (Turbopack)
✓ Running next.config.ts took 84ms
- Cache Components enabled
- Partial Prefetching enabled

  Creating an optimized production build ...
✓ Compiled successfully in 2.8s
  Running TypeScript ...
  Finished TypeScript in 2.8s ...
  Finalizing page optimization ...

Route (app)
┌ ○ /
├ ○ /_not-found
└ ƒ /api/hello


○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand
$ docker run -d --name nextjs-route-handlers-8 -p 3100:3000 -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 node:26.13 npx next start
32b9b0c3ba603e2de10277f2c4fb8af1d83d926e58c759e5961ace654f11b97c
$ until curl -s -o /dev/null http://localhost:3100/; do sleep 0.3; done
$ curl -s -i -X PUT -H "Content-Type: application/json" -d '{"name":"Ada"}' http://localhost:3100/api/hello
HTTP/1.1 200 OK
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
content-type: application/json
Date: Wed, 04 Nov 2026 07:19:53 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked

{"message":"Updated: Ada"}
$ curl -s -i -X PATCH http://localhost:3100/api/hello
HTTP/1.1 405 Method Not Allowed
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
Date: Wed, 04 Nov 2026 07:19:54 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked
$ docker rm -f nextjs-route-handlers-8
nextjs-route-handlers-8

PUT now returns 200 OK with the updated message — a real export, dispatched exactly like GET and POST are. PATCH has no export in this file at all, so it still falls back to the same automatic 405 the lesson’s own DELETE call got.

// app/api/hello/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  const name = request.nextUrl.searchParams.get("name") ?? "World";
  if (name === "crash") {
    throw new Error("boom");
  }
  if (name.length > 20) {
    return NextResponse.json({ error: "name is too long" }, { status: 400 });
  }
  return NextResponse.json({ message: `Hello, ${name}` });
}

export async function POST(request: NextRequest) {
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return NextResponse.json({ error: "body must be valid JSON" }, { status: 400 });
  }
  const { name, age } = body as { name?: unknown; age?: unknown };
  if (typeof name !== "string") {
    return NextResponse.json({ error: "name is required" }, { status: 400 });
  }
  if (typeof age !== "number") {
    return NextResponse.json({ error: "age must be a number" }, { status: 400 });
  }
  return NextResponse.json({ message: `Hello, ${name}`, age }, { status: 201 });
}

export async function PUT(request: NextRequest) {
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return NextResponse.json({ error: "body must be valid JSON" }, { status: 400 });
  }
  const { name } = body as { name?: unknown };
  if (typeof name !== "string") {
    return NextResponse.json({ error: "name is required" }, { status: 400 });
  }
  return NextResponse.json({ message: `Updated: ${name}` });
}

$ docker run --rm -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 -e NPM_CONFIG_UPDATE_NOTIFIER=false node:26.13 npx next build 2>&1 | grep -v -E "Generating static pages using|Collecting page data using|Finished filesystem cache database compaction"
▲ Next.js 16.4.3 (Turbopack)
✓ Running next.config.ts took 64ms
- Cache Components enabled
- Partial Prefetching enabled

  Creating an optimized production build ...
✓ Compiled successfully in 2.3s
  Running TypeScript ...
  Finished TypeScript in 2.4s ...
  Finalizing page optimization ...

Route (app)
┌ ○ /
├ ○ /_not-found
└ ƒ /api/hello


○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand
$ docker run -d --name nextjs-route-handlers-9 -p 3100:3000 -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 node:26.13 npx next start
793ef30a4ad827865cbdc025896dd489ef74c4cc3b27680441f5602ad24dfe6f
$ until curl -s -o /dev/null http://localhost:3100/; do sleep 0.3; done
$ curl -s -i "http://localhost:3100/api/hello?name=crash"
HTTP/1.1 500 Internal Server Error
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
Date: Wed, 04 Nov 2026 07:20:12 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked
$ docker logs nextjs-route-handlers-9 2>&1 | tail -3
✓ Running next.config.ts took 76ms
⨯ Error: boom
    at r (.next/server/chunks/[root-of-the-server]__1qvqb-u26m9mp._.js:1:136)
$ docker rm -f nextjs-route-handlers-9
nextjs-route-handlers-9

Same bare 500 Internal Server Error, same shape of problem: a GET handler that throws is caught by the same framework-level fallback that caught POST’s SyntaxError earlier in this lesson. The real message, Error: boom, only ever reaches the server’s own log — whether the throw comes from parsing a body or from code a reader writes deliberately doesn’t change where Next.js draws the line between “the client gets a response” and “the server gets the detail.” Notice the log’s own location, though: .next/server/chunks/[root-of-the-server]__1qvqb-u26m9mp._.js:1:136 is a minified production build chunk, not app/api/hello/route.ts by name — the build already renamed and bundled the source file away by the time anything reaches this console.

// app/api/static/route.ts — GET never touches the request
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ status: "ok" });
}

$ docker run --rm -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 -e NPM_CONFIG_UPDATE_NOTIFIER=false node:26.13 npx next build 2>&1 | grep -v -E "Generating static pages using|Collecting page data using|Finished filesystem cache database compaction"
▲ Next.js 16.4.3 (Turbopack)
✓ Running next.config.ts took 107ms
- Cache Components enabled
- Partial Prefetching enabled

  Creating an optimized production build ...
✓ Compiled successfully in 3.1s
  Running TypeScript ...
  Finished TypeScript in 2.6s ...
  Finalizing page optimization ...

Route (app)
┌ ○ /
├ ○ /_not-found
├ ƒ /api/hello
└ ○ /api/static


○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand
$ docker run -d --name nextjs-route-handlers-10 -p 3100:3000 -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 node:26.13 npx next start
6cb9413778c8121c116e6b6a3d9e9fe3fa99d3ab140796e5ddc9757ecad9c24d
$ until curl -s -o /dev/null http://localhost:3100/; do sleep 0.3; done
$ curl -s http://localhost:3100/api/static
{"status":"ok"}
$ docker rm -f nextjs-route-handlers-10
nextjs-route-handlers-10

/api/static lands on ○ in the same route table where /api/hello still shows ƒ — one Route Handler, one marker rule, applied per file: nothing to prerender around means ƒ, nothing request-specific to wait for means ○.

No file changes — both route files are already in place from the previous tasks.

$ docker run -d --name nextjs-route-handlers-11 -p 3100:3000 -v "$(pwd)":/root/next-app -v nextjs-modules:/root/next-app/node_modules -w /root/next-app -e NEXT_TELEMETRY_DISABLED=1 node:26.13 npx next start
1979ce183c4648b1eb269c79f3be220f007aee5300997af1de661dd8bcd6a216
$ until curl -s -o /dev/null http://localhost:3100/; do sleep 0.3; done
$ curl -s -i -X OPTIONS http://localhost:3100/api/hello
HTTP/1.1 204 No Content
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
allow: GET, HEAD, OPTIONS, POST, PUT
Date: Wed, 04 Nov 2026 07:20:40 GMT
Connection: keep-alive
Keep-Alive: timeout=5
$ curl -s -i -X OPTIONS http://localhost:3100/api/static
HTTP/1.1 405 Method Not Allowed
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
Allow: GET
Allow: HEAD
Date: Wed, 04 Nov 2026 07:20:40 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked

Method Not Allowed
$ docker rm -f nextjs-route-handlers-11
nextjs-route-handlers-11

The two answers to the same un-exported OPTIONS aren’t even the same shape of response. /api/hello gets 204 No Content and one allow header listing every method the file exports, HEAD and OPTIONS included even though neither has its own export. /api/static gets 405 Method Not Allowed instead, with a body (Method Not Allowed) and two separate Allow headers, one per method it supports (GET, HEAD — confirming HEAD is treated as automatic here too, the same as on /api/hello). The one file-level difference the lesson changed on purpose was which methods each file exports, but the build table already flagged something else: /api/static built ○, /api/hello built ƒ. Next.js’s own automatic handling for an un-exported method isn’t one fixed response — a static route and a dynamic route answer it differently.