home / skills / busirocket / agents-skills / busirocket-nextjs-route-handlers

busirocket-nextjs-route-handlers skill

safe

/skills/busirocket-nextjs-route-handlers

This skill helps you craft thin Next.js route handlers that validate inputs, call services, and return standardized JSON responses.

npx playbooks add skill busirocket/agents-skills --skill busirocket-nextjs-route-handlers

Review the files below or copy the command above to add this skill to your agents.

Files (17)

SKILL.md

3.0 KB

---
name: busirocket-nextjs-route-handlers
description:
  Next.js App Router route handler patterns. Use when creating or refactoring
  route.ts files, implementing API endpoints, validating request inputs, and
  returning standardized JSON responses with proper status codes.
metadata:
  author: cristiandeluxe
  version: "1.0.0"
---

# 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

Overview

This skill provides patterns for building thin, maintainable Next.js App Router route handlers. It focuses on clear validation boundaries, standardized JSON responses, correct HTTP status codes, and guidance on server vs client component decisions. Use it to create or refactor route.ts API endpoints that delegate business logic to services.

How this skill works

Handlers should validate inputs, call a services/ function, and return a standard JSON response shape without embedding business logic or performing IO. The skill enforces response formats: { data } for success and { error: { code, message } } for errors, and maps common outcomes to appropriate HTTP status codes. It also outlines serialization and client/server component boundaries to keep server-only code safe.

When to use it

Creating new app/api/**/route.ts endpoints
Refactoring existing route handlers to remove business logic
Implementing request validation and input guards
Standardizing API responses and status codes
Deciding whether a component should be server or client

Best practices

Keep route handlers thin: validate, call a service, return response
Never perform business logic or IO directly in the handler
Always validate and never return unvalidated request input
Return standardized JSON shapes: { data } on success, { error: { code, message } } on failure
Use appropriate HTTP status codes (200/201/204/400/401/403/404/409/500)
Keep client islands minimal and ensure serialized props from server

Example use cases

An endpoint that validates a POST payload, calls createUser in services, and returns 201 with { data }
A GET route that parses query params, calls a read service, and returns 200 or 404 with standardized error
Refactoring a large route.ts that currently does DB calls into a thin handler plus service module
Implementing input guards for unknown or malicious fields before any service call
Choosing to render layout and page as server components while using small client components for interactivity

FAQ

Where should validation live?

Validate at the handler boundary and in service-level guards; handlers ensure inputs are safe before calling services.

What JSON shape should errors use?

Return { error: { code, message } } and pick an appropriate HTTP status code to reflect the failure reason.