---
name: nextjs-api-route-refactoring-tool
description: "Rewrites an existing Next.js API route into a tidy, modern file: imports grouped, middleware separated, error handling standardized, types added when you choose TypeScript, with every change logged at the top. Use when an existing Next.js API route file is messy and needs its imports, middleware, and error handling reorganized, optionally moving it to TypeScript. Do not use for writing a route from a spec, or optimizing a route for throughput. Related topics: coding, next.js."
---

# Next.js API Route Refactoring Tool

Rewrites an existing Next.js API route into a tidy, modern file: imports grouped, middleware separated, error handling standardized, types added when you choose TypeScript, with every change logged at the top.

## When to use

Use this skill when an existing Next.js API route file is messy and needs its imports, middleware, and error handling reorganized, optionally moving it to TypeScript. Do not use it for writing a route from a spec, or optimizing a route for throughput.

## 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. Record the route's observable behavior: accepted methods, status codes, bodies, and side effects, as the contract to preserve.
3. Group imports, extract inline middleware into named functions, and route every response through one helper in the chosen error style.
4. Add NextApiRequest and NextApiResponse types plus body and response types when TypeScript is selected.
5. Insert a minimal body schema check returning 400 when validation is on, rename the handler as given, and add the changelog comment at the top.
6. Diff the result against the behavior contract to confirm nothing changed and output the file plus a short change summary.

## Inputs

- **Original file path** (free text, e.g. "src/pages/api/example.js")
- **Current route source** (longer free text)
- **Language** (choose one: JavaScript, TypeScript)
- **Error handling style** (choose one: try/catch, next-response, middleware)
- **Include request validation** (choose one: Yes, No)
- **Rename exported handler** (free text, e.g. "newHandlerName")
- **Add inline comments** (choose one: Yes, No)

## Output

The refactored file in a fenced block tagged js or ts, starting with a changelog comment, followed by a brief plain-text summary of the applied changes.

## Prompt template

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

### Next.js API Route Refactoring Tool

Refactor this Next.js API route without changing what it does.

- Original file path: {{Original file path}}
- Current route source: {{Current route source}}
- Language: {{Language}}
- Error handling style: {{Error handling style}}
- Include request validation: {{Include request validation}}
- Rename exported handler: {{Rename exported handler}}
- Add inline comments: {{Add inline comments}}

Read the file and write down its observable behavior first: methods accepted, status codes and bodies returned, side effects; that list is the contract the refactor must keep. Group imports (framework, third party, local), pull any inline middleware into named functions above the handler, and give every response path the same shape through a single helper in the chosen error style: try/catch wrapping the body, next-response style helpers, or a middleware wrapper that catches throws. When TypeScript is selected, type req and res with NextApiRequest and NextApiResponse and add types for the body and the response. When validation is on, add a minimal schema check for the body at the top of the handler using a library of your choice, returning 400. Rename the exported handler only to the name given. Add one-line comments per section when requested and nothing more. Put a changelog comment at the top of the file listing each transformation applied. Add no dependencies beyond what the options require. Return the refactored file in triple backticks tagged with the language, then a brief plain-text summary of the changes.

## Pitfalls

- Changing a status code or response field while standardizing error handling, which breaks existing clients silently.
- Adding a validation library when the options did not ask for it, which the team now has to audit.
- Renaming the exported handler and missing the import elsewhere in the project, which the summary should warn about.
