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