route-handlers_skill

Overview

This skill helps you create and maintain Next.js App Router route handlers for building API endpoints, handling requests, streaming responses, and managing headers, cookies, CORS, and caching. It focuses on practical code patterns and conventions for route.ts files so you can implement RESTful routes, dynamic params, and AI/LLM streaming quickly.

How this skill works

It inspects the desired endpoint path and maps it to the app/.../route.ts file convention, then scaffolds or explains exported HTTP method handlers (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD). It shows how to read request bodies, query and URL params, headers, set responses and headers with NextResponse or Response, manage cookies, return redirects, stream text or LLM output, and implement common error handling and CORS patterns.

When to use it

• You need to add an API endpoint in a Next.js App Router project (route.ts).
• You want to handle POST data, file/form submissions, or JSON bodies.
• You need dynamic route parameters (e.g., /api/posts/[id]).
• You want to stream server-sent events or LLM output to clients.
• You must set cookies, custom headers, redirects, or CORS responses.
• You need guidance on caching behavior or forcing dynamic responses.

Best practices

• Use app/.../route.ts files and export functions named for HTTP methods (GET, POST, etc.).
• Validate and parse request bodies explicitly; return 4xx for validation errors and 5xx for unexpected failures.
• Prefer NextResponse.json for JSON responses and set Cache-Control or dynamic = 'force-dynamic' when freshness is required.
• Implement OPTIONS to handle CORS preflight and add Access-Control-Allow-Origin on responses when needed.
• Use ReadableStream for streaming text or LLM chunks, and set appropriate Content-Type and cache headers.
• Keep side effects (DB, auth) explicit and return clear status codes for clients.

Example use cases

• Create a CRUD users API with app/api/users/route.ts implementing GET and POST.
• Build a streaming chat endpoint that proxies an LLM and forwards chunks to the browser.
• Implement an authenticated resource that reads Authorization header and returns 401 when missing.
• Serve paginated results using query parameters page and limit parsed from request.url.
• Set an httpOnly session cookie on login and redirect to a protected route.