Next.js

Verified against Claude Code · 2026-07-22

Design a Route Handler that doesn't leak Express habits into the App Router

Turns an API requirement into a properly structured app/api route.ts — right runtime, right status codes, right cache invalidation, not a copy-pasted Express handler.

Claude CodeGitHub CopilotCursor 2.1

The prompt

Ready to copy — highlighted parts are example details you can swap.

<context>
Endpoint purpose: Lets an authenticated user update their team's billing address
HTTP methods needed: GET and PATCH
Request/response shape: PATCH body: { line1, city, postalCode, country }; response: the updated team object
Runtime preference, if any: Needs Node.js — the handler calls a Postgres client that isn't edge-compatible
</context>

<task>
Design the Route Handler(s) for this endpoint as they'd live in app/api/.../route.ts, using the Web-standard Request/Response APIs (NextRequest/NextResponse), not an Express-style (req, res) signature — there is no res object here.
</task>

<requirements>
- Export one named async function per HTTP method actually needed (GET, POST, PATCH, DELETE, etc.) — never a single catch-all handler that branches on req.method internally.
- Validate the request body/query against a schema before touching any business logic; return a 400 with field-level errors on validation failure, not a generic 500.
- Choose and state the runtime explicitly (export const runtime = 'nodejs' | 'edge') based on what the handler actually needs — edge runtime has no access to Node.js-only APIs (fs, most native modules, some crypto), so justify edge only if nothing in the handler needs those.
- If this handler causes data that's cached elsewhere in the app to go stale (a mutation), call revalidatePath or revalidateTag for the specific affected paths/tags after the mutation succeeds — never before, and never a broad revalidation when a narrow one would do.
- Return real HTTP status codes (201 on create, 204 on empty delete response, 409 on conflict, etc.) — not 200 for everything with an error message in the body.
</requirements>

<output_format>
The route.ts code, followed by a short list: which status codes are used and when, which runtime was chosen and why, and exactly what gets revalidated after a mutation.
</output_format>
Customize the highlighted detailsoptional — the prompt above already works

Why this works

Route Handlers use the standard Web Request/Response objects, not Express's (req, res) — a distinction generic 'build me an API endpoint' prompts routinely get wrong because most training data on Next.js APIs predates the App Router, or was written for the Pages Router's req/res-style API routes. Naming the exact export shape (one async function per HTTP method) and forcing an explicit runtime choice stops the model from defaulting to edge for convenience and then silently failing on a Node-only dependency at deploy time instead of at review time. The revalidatePath/revalidateTag requirement closes the gap that's easy to forget: a Route Handler that mutates data doesn't automatically invalidate anything cached elsewhere in the app — that has to be called explicitly, and scoped to the specific path or tag rather than nuked broadly.

What you get back

PATCH /api/teams/[id]/billing-address returns 400 with { errors: { postalCode: 'required' } } on a bad payload, 200 with the updated team on success, then calls revalidateTag('team-' + id) so the team settings page (which reads the same data via a tagged fetch) picks up the change on next load instead of serving a stale cached copy.

Verified against

Claude Code Sonnet 4.6 · 2026-07-22

GitHub Copilot 2026.7 · 2026-07-25

Changelog

  • 2026-07-22 Initial version, tested against Claude Code on Next.js 16 route handlers.
Pairs with our free JSON Formatter & Validator — no signup, runs in your browser.

Need this built into your business?

If a prompt isn't enough — custom software, built and maintained for you — that's Scult's day job.

EXPLORE CUSTOM SOFTWARE
All Next.js prompts

Check your AI visibility

One URL in, a 0–100 score and the exact fixes out.

RUN THE CHECK

Browse all the tools

15 tools across six categories
13 of them never send your data anywhere

Free · No signup · No trial clock

SEE THE DIRECTORY