---
name: nextjs-api-route-builder
description: "Writes a complete JavaScript Next.js API route you can drop into pages/api: method guard, optional body validation, an optional auth check, and the error-handling style your codebase already uses. Use when a plain JavaScript API route for pages/api is needed fast with a method guard, optional auth, and a chosen error-handling style. Do not use for strict TypeScript routes with zod and next-auth, or refactoring a route that already exists. Related topics: coding, next.js."
---

# Next.js API Route Builder

Writes a complete JavaScript Next.js API route you can drop into pages/api: method guard, optional body validation, an optional auth check, and the error-handling style your codebase already uses.

## When to use

Use this skill when a plain JavaScript API route for pages/api is needed fast with a method guard, optional auth, and a chosen error-handling style. Do not use it for strict TypeScript routes with zod and next-auth, or refactoring a route that already exists.

## 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. Open with the method guard so other methods receive 405 and an Allow header.
3. Insert the auth check at the top when required, returning 401 before the body is read, with a marked plug-in point for the real check.
4. Validate required fields and types by hand against the given schema and answer 400 with the field list.
5. Implement the handler in the chosen error-handling style and shape the success response exactly like the example.
6. Comment each block in one line and return the file as a js code block headed by its path comment.

## Inputs

- **Route path** (free text, e.g. "/api/example")
- **HTTP method** (choose one: GET, POST, PUT, DELETE, PATCH)
- **Request body schema (optional)** (longer free text)
- **Response shape** (longer free text)
- **Require authentication** (choose one: Yes, No)
- **Error handling style** (choose one: Throw errors, Return error object, Use nextApiHandler)

## Output

A single code block tagged js: a path comment, imports if any, the auth helper, the handler with method guard, validation, business logic placeholder, and the default export.

## Prompt template

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

### Next.js API Route Builder

Write a ready-to-use Next.js API route in JavaScript.

- Route path: {{Route path}}
- HTTP method: {{HTTP method}}
- Request body schema (optional): {{Request body schema (optional)}}
- Response shape: {{Response shape}}
- Require authentication: {{Require authentication}}
- Error handling style: {{Error handling style}}

Keep it plain JavaScript with no build-time types, and keep it self-contained so it runs the moment the file lands in pages/api. Begin with the method guard: anything but the chosen method gets 405 and an Allow header. When authentication is required, read the token or session at the top and return 401 before touching the body; leave a clearly marked function where the real check plugs in. When a body schema is given, check required fields and types by hand and answer 400 with the list of missing or wrong fields, since the point of this route is zero extra dependencies. Apply the chosen error-handling style consistently: throwing lets a wrapper translate errors, returning an error object keeps every exit explicit, and nextApiHandler style centralizes both. Shape the success response exactly like the example, including status code and field names. Add a comment above each block explaining its purpose in one line. Return the single file as a code block tagged js, starting with a comment naming its path.

## Pitfalls

- Pulling in a validation library for a route whose whole appeal is no new dependencies.
- Mixing thrown errors and returned error objects in one handler, so callers cannot predict the failure shape.
- Reading req.body on a GET route, which is always undefined and masks a wrong method.
