validated-handler_skill

Overview

This skill provides a reusable, type-safe API route handler for Next.js App Router that integrates Zod validation automatically. It reduces boilerplate, enforces consistent error responses, and preserves full TypeScript inference for route inputs. Use it to centralize validation and error handling across GET/POST/PATCH routes.

How this skill works

The handler inspects the incoming NextRequest, extracts raw input from either query params or request body based on configuration, and runs a Zod schema.safeParse on that input. If validation fails it returns a standardized 400 response with issue details; if it succeeds the handler invokes your route logic with a typed input object. Errors during execution are logged and returned as a generic 500 response.

When to use it

• Creating Next.js App Router API routes that need input validation
• Eliminating repeated parsing and validation boilerplate across routes
• Enforcing consistent error formats for client-side handling
• Building type-safe endpoints with full TypeScript inference
• Implementing pagination, filter, or CRUD endpoints that share schemas

Best practices

• Define reusable Zod schemas (e.g., paginationInputSchema) and extend them per route
• Set the validation source explicitly: 'query' for URL params or 'body' for JSON payloads
• Return business-layer errors from inside your handler but rely on the validated handler for input errors
• Use errorTransform when you need custom error shapes or localization
• Keep authentication and authorization inside your route handler after validation

Example use cases

• GET /api/items with page and limit parsed and coerced via pagination schema
• POST /api/providers validating request body for required fields and email format
• PATCH /api/providers/[id] validating partial updates in the request body
• Authenticated endpoints where session is validated after input validation
• Endpoints combining query filters and request body filters with separate schemas