api-endpoint-scaffold

jamesjlundin's avatarfrom jamesjlundin

Scaffold new Next.js API endpoints with authentication, rate limiting, and tests. Use when creating new API routes, adding endpoints, or building API features.

⭐8stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026
[API Helpers]

When & Why to Use This Skill

This Claude skill streamlines the development of production-ready Next.js API endpoints by automating the scaffolding process. It ensures high-quality code by integrating essential features such as authentication, rate limiting, and Zod-based request validation, while also generating comprehensive integration tests to maintain security and reliability standards.

Use Cases

  • Rapidly creating a new POST endpoint for a 'User Profile' update feature with built-in Zod validation and automated integration tests.
  • Adding a secure GET route for sensitive data that requires mandatory authentication and specific rate-limiting configurations to prevent abuse.
  • Standardizing API development across a project by generating boilerplate code that follows strict repository patterns for error handling and response schemas.
  • Building out a suite of CRUD endpoints for a new feature while ensuring all routes pass TypeScript, linting, and integration test checks automatically.
nameapi-endpoint-scaffold
descriptionScaffold new Next.js API endpoints with authentication, rate limiting, and tests. Use when creating new API routes, adding endpoints, or building API features.
allowed-toolsRead, Grep, Glob, Write, Edit

API Endpoint Scaffold

Creates production-ready API endpoints following this repo's patterns.

When to Use

  • "Create an endpoint for..."
  • "Add API route for..."
  • "I need a POST/GET endpoint"
  • "Build an API for {feature}"

Prerequisites

Before creating an endpoint, confirm:

  1. Endpoint path (e.g., /api/users/profile)
  2. HTTP methods needed (GET, POST, PUT, DELETE)
  3. Authentication required? (default: yes)
  4. Rate limiting config (requests/window)
  5. Request/response schema

Procedure

Step 1: Create Route File

Path: apps/web/app/api/{path}/route.ts

Use the template in templates.md.

Step 2: Add Rate Limiting (if needed)

Import from existing pattern:

import { withUserRateLimit } from '../_lib/withUserRateLimit';
import { createRateLimiter } from '@acme/security';

Step 3: Add Request Validation

Use Zod for schema validation:

import { z } from 'zod';

const RequestSchema = z.object({
  field: z.string().min(1),
});

Step 4: Create Integration Test

Path: packages/tests/src/{feature}.test.ts

See templates.md for test template.

Step 5: Verify

Run these commands:

  1. pnpm typecheck - Type check
  2. pnpm lint - Lint check
  3. pnpm test:integration - Run tests

Checklist

  • Route file created at correct path
  • Authentication check using getCurrentUser()
  • Rate limiting applied via withUserRateLimit
  • Request validation with Zod
  • Proper error responses (400, 401, 403, 429, 500)
  • Integration test created
  • TypeScript types pass
  • ESLint passes

Guardrails

  • ALWAYS use getCurrentUser() from @acme/auth for auth
  • ALWAYS apply rate limiting to user-facing endpoints
  • NEVER expose internal errors to clients
  • NEVER skip request validation
  • If unsure about rate limit config, ask user