kb-api

Standardize Next.js 16+ server actions and route handlers with Zod validation and ActionResult contracts.

Updated May 19, 2026
One-click install
npx skills add https://github.com/TimeKast/AgendaInteligente --skill kb-api
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: kb-api
Source: https://github.com/TimeKast/AgendaInteligente/tree/main/.claude/skills/kb-api
Command: npx skills add https://github.com/TimeKast/AgendaInteligente --skill kb-api

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents inconsistent API behavior in Next.js 16+ by standardizing how server actions and route handlers handle validation, authorization, revalidation, and error responses.

Core Features & Use Cases

  • ActionResult<T> Contract: Uses a discriminated union to reliably separate success data from user-facing error strings for cleaner consumer branching.
  • Portable CRUD Action Signatures: Defines consistent getEntities, getEntityById, createEntity, updateEntity, and deleteEntity semantics that work across projects.
  • Boundary-First Validation: Enforces Zod safeParse exactly once at the action or route boundary to establish a clear trust boundary.
  • Success-Only Cache Invalidation: Applies revalidatePath only after a real mutation succeeds, and never on read-only actions.
  • Next.js 16+ Correctness for params/searchParams: Treats params and searchParams as Promises and parses them safely with await.

Quick Start

Implement your server action or route handler using the ActionResult<T> pattern, validate inputs with Zod safeParse at the boundary, and call revalidatePath only on the success path after the mutation completes.

Frequently Asked Questions about kb-api

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I handle Next.js server action errors consistently?

Use an ActionResult<T> discriminated-union contract to reliably separate success data from user-facing error strings in Next.js server actions, ensuring cleaner consumer branching for consistent error handling.

When should I use revalidatePath in Next.js server actions?

Apply revalidatePath only after a real mutation succeeds in your Next.js server action, and never on read-only actions, to ensure success-only cache invalidation and prevent stale data.

Should I choose Next.js server actions or route handlers for my API?

Choose Next.js server actions or route handlers based on your mutation semantics and HTTP status/body conventions; server actions standardize validation via Zod safeParse, while route handlers require explicit HTTP status codes.

How do I validate inputs at the boundary in Next.js server actions?

Enforce Zod safeParse exactly once at the action or route boundary in Next.js to establish a clear trust boundary, validating inputs before processing mutations or returning ActionResult<T> responses.

Does Next.js 16 require awaiting params and searchParams?

Yes, Next.js 16+ treats params and searchParams as Promises, requiring you to safely await and parse them before use in server actions and route handlers to avoid runtime errors.

What is the best way to structure CRUD endpoints in Next.js?

Define portable CRUD action signatures like getEntities, getEntityById, createEntity, updateEntity, and deleteEntity in Next.js to maintain consistent semantics and validation across projects.