busirocket-nextjs

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)

busirocket-react - Component patterns and Server/Client boundaries
busirocket-validation - Validation strategies (Zod schemas, guard helpers)
busirocket-core-conventions - File structure and boundaries

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