mis-nextjs-api-guards

Implements declarative guard pipelines for Next.js App Router API route handlers.

Updated Oct 7, 2023
One-click install
npx skills add https://github.com/AhmedElbialy148/Portfolio --skill mis-nextjs-api-guards-ahmedelbialy148
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mis-nextjs-api-guards
Source: https://github.com/AhmedElbialy148/Portfolio/tree/main/.cursor/skills/mis-nextjs-api-guards
Command: npx skills add https://github.com/AhmedElbialy148/Portfolio --skill mis-nextjs-api-guards-ahmedelbialy148

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires zod, @supabase/ssr, @supabase/supabase-js, @upstash/redis, and includes references (resource) and assets (resource) components.

What problem does it solve? Next.js App Router route handlers often accumulate ad-hoc authentication, authorization, validation, and error-handling code that is inconsistent, untyped, and hard to audit. This Skill standardizes every API route around a declarative defineRoute({ guards: [...], handler }) pattern with a progressively typed context and a single response envelope. ## Core Features & Use Cases - Declarative guard pipeline: Compose authentication, RBAC roles, permissions, ownership, rate limiting, idempotency, CORS/CSRF, timeouts, and Zod validation as an ordered array, with ctx.principal and ctx.body inferred automatically. - Pluggable adapters: Wire Supabase auth, Upstash Redis rate limiting and idempotency, and structured logging once via configureGuards(...), with Edge-safe defaults and custom adapter support. - Consistent error envelope: Every response carries ok, a stable machine code, and an X-Request-Id correlation id, with typed ApiError classes and always-on audit logging. - Use Case: When adding a PATCH endpoint that only managers can call, declare rateLimit, auth, roles("admin", "manager"), and validate({ body }) guards and keep the handler thin, instead of hand-writing session checks and error JSON. ## Quick Start Ask the AI to protect a Next.js route handler using the MIS guard pipeline, for example by adding auth, role checks, rate limiting, and Zod body validation to an existing route.ts file.

Frequently Asked Questions about mis-nextjs-api-guards

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

FAQPage Schema
How do I add authentication and role checks to a Next.js API route?▼

Export the verb with defineRoute and list guards in order: auth() verifies the session and adds ctx.principal, then roles("admin", "manager") or permissions("orders:write") enforce authorization. Failed checks return 401 or 403 in the standard envelope.

How do I rate limit a Next.js API route on Vercel?▼

Add rateLimit({ window: "1m", limit: 20 }) before auth() so unauthenticated floods are rejected cheaply. Use the Upstash Redis adapter in production because it shares state across serverless isolates; the in-memory adapter is per-process and only suitable for development and tests.

Does this guard pipeline work with the Next.js Edge runtime?▼

Yes, the default adapters are Edge-safe: Upstash uses a REST API and @supabase/ssr runs on Edge. Long upstream calls such as Google Apps Script should use the Node runtime with a timeout() guard instead.

Why use a guards array instead of withAuth higher-order wrappers?▼

Nested HOF wrappers thread accumulated context through multiple generic layers, so TypeScript often widens ctx and loses inference past three wrappers. The flat guards tuple folds all additions in one pass, keeping ctx.principal and ctx.body fully typed, and reads top-to-bottom in execution order.

Why does ctx.body replace calling req.json() in the handler?▼

The validate({ body }) guard parses the request stream once with Zod and exposes the typed result as ctx.body, dropping any fields not in the schema to prevent mass-assignment. Calling req.json() again fails because the stream is already consumed.

What are the limitations of the guard pipeline in v1.0?▼

The type fold infers what each guard adds but does not yet enforce ordering at compile time, so placing roles() before auth() fails only at runtime. Ordering enforcement via the Needs phantom type is planned for v1.1; until then follow the canonical guard order.