Next.js Route Handlers
Patterns for thin, maintainable route handlers in Next.js App Router.
When to Use
Use this skill when:
- Creating or refactoring
app/api/**/route.ts files
- Implementing API endpoints
- Validating request inputs
- Returning standardized JSON responses
- Deciding server vs client component boundaries
Non-Negotiables (MUST)
- Route handlers must be thin: validate input, call a
services/ function,
return a response.
- No business logic or IO directly in the handler.
- Never return unvalidated request input.
- Use standard JSON response shapes:
{ data } for success,
{ error: { code, message } } for errors.
- Use appropriate HTTP status codes (200, 201, 204, 400, 401, 403, 404, 409,
500).
Server vs Client Components
app/**/page.tsx and app/**/layout.tsx are Server Components by
default.
- Use Client Components only when you need: state/event handlers, effects,
browser-only APIs.
'use client' creates a boundary; keep client islands small.
- Props from Server -> Client must be serializable.
Rules
Next.js App Router
nextjs-server-vs-client - Server vs Client Components (defaults, when to use
client)
nextjs-serializable-props - Props must be serializable from Server to Client
nextjs-protecting-server-code - Protecting server-only code from client
imports
nextjs-special-file-exports - Allowed extra exports for Next.js special
files
Route Handlers
nextjs-route-placement - Route handler placement and conflicts with pages
nextjs-thin-handler-rule - Thin handler rule (STRICT)
nextjs-http-methods - Supported HTTP methods
nextjs-caching-model - Caching model for route handlers
nextjs-cache-components - Cache Components note for route handlers
API Response Shapes
nextjs-response-shapes - Standard JSON response shapes (success/error)
nextjs-status-codes - HTTP status codes to use
nextjs-response-rules - Rules for API responses (validation, error handling)
Validation
nextjs-validation-boundaries - Where validation lives (route handlers,
services, utils)
nextjs-validation-patterns - Validation patterns (unknown inputs, guards)
nextjs-validation-helpers - Recommended validation helpers
nextjs-validation-rules - Validation rules (no inline types/helpers)
How to Use
Read individual rule files for detailed explanations and code examples:
rules/nextjs-thin-handler-rule.md
rules/nextjs-response-shapes.md
rules/nextjs-validation-boundaries.md
Each rule file contains:
- Brief explanation of why it matters
- Code examples (correct and incorrect patterns)
- Additional context and best practices