home / skills / busirocket / agents-skills / busirocket-nextjs

busirocket-nextjs skill

safe

This skill helps you design thin, validated Next.js App Router route handlers with standardized JSON responses and proper status codes.

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

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

Files (17)

SKILL.md

3.2 KB

---
name: busirocket-nextjs
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)

## Related Skills

- `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

Overview

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

How this skill works

The skill enforces a thin-handler approach: validate request data, call a service function, and return a standardized JSON response. It separates I/O and business logic out of the handler into services, uses validation helpers or schemas, and maps outcomes to proper HTTP status codes and response shapes. It also documents rules for server vs client components and serializable props.

When to use it

Creating new app/api/**/route.ts API endpoints
Refactoring existing route handlers to remove business logic
Validating request inputs and preventing unvalidated output
Standardizing JSON responses and status codes across endpoints
Deciding or enforcing server vs client component boundaries

Best practices

Keep handlers thin: validate, call services/, return response
Never perform business logic or external I/O inside handlers
Never return raw or unvalidated request input to clients
Return { data } on success and { error: { code, message } } on error
Use appropriate HTTP status codes (200/201/204, 4xx for client, 500 for server)
Keep client components minimal and only when necessary; serialize props

Example use cases

Implementing a POST /api/users route: validate body, call services/createUser, return 201 with { data }
Refactoring a monolithic handler that reads DB directly into a thin handler + services pattern
Adding request validation with Zod or guard helpers to protect against unknown inputs
Creating consistent error handling middleware that maps service errors to { error } shapes
Deciding whether a component should be server or client based on state and browser APIs

FAQ

Where should validation live?

Validation belongs at the handler boundary; use shared schemas or guard helpers and then pass validated data to services.

What response shape should I return on success?

Return a JSON object with a top-level data key, e.g. { data: ... }, and use error objects for failures.