---
name: nextjs-api-route-formatter
description: "Delivers a TypeScript Next.js API route with typed query parameters, body, and response, plus a short fetch example the frontend can copy, so both sides of the call agree on the types. Use when a TypeScript API route needs its query parameters, body, and response typed and exported so the frontend can import the types and call it correctly. Do not use for routes with zod and session middleware composition, or plain JavaScript routes. Related topics: coding, next.js."
---

# Next.js API Route Formatter

Delivers a TypeScript Next.js API route with typed query parameters, body, and response, plus a short fetch example the frontend can copy, so both sides of the call agree on the types.

## When to use

Use this skill when a TypeScript API route needs its query parameters, body, and response typed and exported so the frontend can import the types and call it correctly. Do not use it for routes with zod and session middleware composition, or plain JavaScript routes.

## 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. Define and export the Query, RequestBody, and Response types from the spec so the handler and the frontend share them.
3. Parse req.query into the Query type with explicit coercion and answer 400 for missing or malformed required parameters.
4. Add the 405 method guard and, when required, the 401 auth check before any parsing.
5. Implement the handler typed as NextApiHandler of the Response type with a comment marking each section.
6. Write the typed fetch usage example that imports the exported types and handles the error statuses, then output both blocks.

## Inputs

- **HTTP method** (choose one: GET, POST, PUT, DELETE, PATCH)
- **Route path** (free text, e.g. "/api/example")
- **Description** (longer free text)
- **Query parameters (optional)** (longer free text)
- **Request body schema (for POST or PUT or PATCH)** (longer free text)
- **Authentication required** (choose one: Yes, No)
- **Response shape** (longer free text)

## Output

Two blocks: the complete route file as a code block tagged ts with exported types and a commented handler, then a short markdown usage example with a typed fetch call.

## Prompt template

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

### Next.js API Route Formatter

Write a TypeScript Next.js API route from this spec, with a usage example for the frontend.

- HTTP method: {{HTTP method}}
- Route path: {{Route path}}
- Description: {{Description}}
- Query parameters (optional): {{Query parameters (optional)}}
- Request body schema (for POST or PUT or PATCH): {{Request body schema (for POST or PUT or PATCH)}}
- Authentication required: {{Authentication required}}
- Response shape: {{Response shape}}

Define the types first and export them: a Query type from the query parameter list, a RequestBody type from the schema, and a Response type from the response shape, so the frontend imports the same definitions the handler uses. Parse req.query into the Query type explicitly, because every query value arrives as a string or string array; coerce numbers and booleans and answer 400 when a required parameter is missing or malformed. Guard the method with 405 and an Allow header. When authentication is required, check the session or token first and return 401. Mark the handler sections with comments: types, guards, parsing, logic, response. Type the handler as NextApiHandler of the Response type so a wrong return shape fails to compile. After the file, add a brief usage example in markdown: a typed fetch call from a component or hook that imports the exported types and handles the error status codes. Return the full .ts file as one code block tagged ts, then the usage example as a separate block.

## Pitfalls

- Treating req.query values as numbers or booleans when Next.js always delivers strings or string arrays.
- Keeping the types private to the route file, which forces the frontend to retype them and drift.
- Returning a different shape on error than the Response type declares without widening the handler type.
