---
name: nextjs-api-route-architect
description: "Builds a strict-TypeScript Next.js API route with a zod-validated request, a typed response, next-auth session checks, and composed middleware, so the endpoint is production-ready the first time it runs. Use when a Next.js API route must be strict TypeScript with zod validation, typed responses, and a next-auth or token check before it ships. Do not use for a quick JavaScript route, debugging a failing route, or writing route documentation. Related topics: coding, next.js."
---

# Next.js API Route Architect

Builds a strict-TypeScript Next.js API route with a zod-validated request, a typed response, next-auth session checks, and composed middleware, so the endpoint is production-ready the first time it runs.

## When to use

Use this skill when a Next.js API route must be strict TypeScript with zod validation, typed responses, and a next-auth or token check before it ships. Do not use it for a quick JavaScript route, debugging a failing route, or writing route documentation.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Convert the request and response schemas into zod objects and infer their TypeScript types, so runtime checks and types share one source.
3. Add the method guard that answers 405 with an Allow header for anything but the chosen method.
4. Implement the chosen authentication ahead of validation and return 401 before any schema detail is exposed.
5. Compose the selected middleware as typed higher-order wrappers in the listed order, with validateBody returning 400 and flattened zod issues.
6. Write the handler with a typed response union and a try/catch that logs with the route path, then output the full ts file in order.

## Inputs

- **Route path** (free text, e.g. "/api/example")
- **HTTP method** (choose one: GET, POST, PUT, DELETE, PATCH)
- **Authentication** (choose one: None, JWT, NextAuth, API Key)
- **Request body schema** (longer free text)
- **Success response schema** (longer free text)
- **Middleware** (choose any: rateLimit, cors, validateBody, logRequest)

## Output

One code block tagged ts containing the full route file in this order: imports, zod schemas and inferred types, middleware wrappers, the handler, the default export.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Next.js API Route Architect

Write a production-ready, fully typed Next.js API route.

- Route path: {{Route path}}
- HTTP method: {{HTTP method}}
- Authentication: {{Authentication}}
- Request body schema: {{Request body schema}}
- Success response schema: {{Success response schema}}
- Middleware: {{Middleware}}

Target Next.js 13 API route conventions under pages/api with strict TypeScript, zod for validation, and next-auth for sessions. Start by converting both schemas into zod objects and inferring the TypeScript types from them, so the request type, the response type, and the runtime check never drift. Reject any method other than the chosen one with 405 and an Allow header. Run authentication before validation, so unauthenticated callers learn nothing about the schema: for NextAuth call getServerSession, for JWT verify the bearer token, for API Key compare against an environment variable in constant time. Compose the selected middleware as small higher-order functions wrapping the handler in the order listed, with validateBody parsing the body through the zod schema and returning 400 with the flattened issues. Type the response as NextApiResponse of a union of the success type and an error shape. Wrap the handler body in try/catch that logs the error with the route path and returns 500 without leaking the message. Return the complete file as one code block tagged ts with imports, the schemas and types, each middleware, the handler, and the default export in that order.

## Pitfalls

- Validating the body before checking the session, which lets anonymous callers probe the schema through error messages.
- Declaring request types by hand next to the zod schema, so the two drift the first time a field changes.
- Returning the caught error message in the 500 body, which leaks stack and database details.
- Forgetting the Allow header on the 405 response, which clients and proxies rely on.
