Scaffolding REST API

Scaffolding REST API

Overview

This skill creates a new TypeScript REST API project or adds a new resource to an existing Fastify project. It enforces one opinionated stack (Fastify + Zod + pino + Vitest) and generates code that follows the same validation, error, and observability patterns across every endpoint.

Quick reference

Workflow

Scaffold progress:
- [ ] Step 1: Confirm project name and target directory
- [ ] Step 2: Run init.sh to create the skeleton
- [ ] Step 3: Wire base plugins (sensible, cors, helmet, rate-limit, swagger)
- [ ] Step 4: Configure error handler + logger + graceful shutdown
- [ ] Step 5: Add health and readiness endpoints
- [ ] Step 6: For each resource the user describes, run gen_resource.ts
- [ ] Step 7: Generate OpenAPI spec and verify it parses
- [ ] Step 8: Run the test suite and lint
- [ ] Step 9: Print next steps (run locally, deploy, add auth)

Step 1 — Confirm inputs

Ask the user:

• Project name (default kebab-case).
• Package manager (pnpm preferred; accept npm/yarn if user insists).
• Target directory (must not already contain a package.json).

Step 2 — Create skeleton

scripts/init.sh <project-name>

Produces this layout:

<project>/
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── .env.example
├── src/
│   ├── app.ts                  # Fastify instance + plugin wiring
│   ├── server.ts               # HTTP listen + graceful shutdown
│   ├── lib/
│   │   ├── env.ts              # Zod-validated env loader
│   │   ├── errors.ts           # AppError class + codes
│   │   └── logger.ts           # pino instance
│   └── routes/
│       └── health.ts           # /healthz + /readyz
└── test/
    └── health.test.ts

Step 3 — Base plugins

Wire these in src/app.ts in this exact order:

1. @fastify/sensible — adds reply.notFound(), reply.badRequest(), etc.
2. @fastify/helmet — secure headers by default.
3. @fastify/cors — configured from env.CORS_ORIGINS (comma-separated, no * in production).
4. @fastify/rate-limit — global: 100 req/min per IP; per-route overrides allowed.
5. @fastify/swagger + @fastify/swagger-ui — OpenAPI 3.1 spec generator.

Step 4 — Error handler

Every error response uses this envelope:

{
  "error": {
    "code": "validation_error",
    "message": "body.email is not a valid email",
    "details": [{"path": "body.email", "issue": "invalid_string"}]
  }
}

Map Zod issues to validation_error. Map unknown errors to internal_error and do not leak the stack; log it at error level with the request id instead.

Step 5 — Health endpoints

• GET /healthz — returns 200 immediately. Used by load balancer liveness.
• GET /readyz — pings every registered dependency (DB, cache, queue) with a 2s timeout; returns 200 if all healthy, 503 otherwise.

Step 6 — Resource generator

The user describes a resource like this:

name: user
fields:
  id: { type: uuid, readonly: true }
  email: { type: email, required: true }
  name: { type: string, max: 120 }
  createdAt: { type: datetime, readonly: true }
operations: [list, get, create, update, delete]
auth: required

scripts/gen_resource.ts emits:

• src/routes/<name>.ts — one file per resource, all handlers present.
• src/schemas/<name>.ts — Zod schemas (Create, Update, Public).
• test/<name>.test.ts — 5 tests per operation (200, 400, 401, 404, 500).

Step 7 — OpenAPI spec

Run the app in "spec" mode:

pnpm spec > openapi.json

Validate with a JSON Schema validator before shipping. The GET /openapi.json endpoint is live in dev; disable in production unless the API is public.

Step 8 — Tests and lint

pnpm test
pnpm lint
pnpm tsc --noEmit

All three must pass before declaring done.

Step 9 — Next steps

Print a short checklist:

• How to run locally: pnpm dev
• How to build: pnpm build
• Where to add auth next (suggest @fastify/jwt with asymmetric keys)
• Where to add DB layer next (suggest Drizzle + Postgres)

Validation conventions

• One Zod schema per route at route.schema = { body, params, query, response }.
• response schemas are REQUIRED on every route. No implicit serialization.
• Error responses always match the envelope; do not pass through library errors.
• Every POST/PUT/PATCH has a body schema with strict() to reject unknown keys.

Rate limiting defaults

• Global: 100 req/min per IP.
• POST /auth/* (if added later): 10 req/min per IP.
• POST /password-reset: 3 req/15min per IP + 3 req/15min per email hash.

Logging conventions

Use pino bindings:

req.log.info({ userId, action: "user.create" }, "user created");

Do not log request bodies. Do not log Authorization headers. Do not log any field named password, token, secret, key, or matching *_secret.

Examples

Example 1 — Bootstrap a greenfield API Input: "bootstrap a REST API for a URL shortener with create/redirect/list" Behavior: Creates the project skeleton, generates a link resource with operations [create, get, list], adds a custom GET /:shortcode redirect route, emits OpenAPI spec, runs tests, prints deploy notes.

Example 2 — Add a resource to an existing project Input: "add an Invoice resource to my Fastify API" Behavior: Detects existing src/routes layout, generates invoice.ts, schemas, and tests following the same patterns as existing resources. Does NOT overwrite existing files — asks before each write.

Example 3 — Generate only the OpenAPI spec Input: "export the OpenAPI spec for my API" Behavior: Runs the app in spec mode, writes openapi.json, validates it, prints a summary of endpoints/schemas.

Non-goals

• No GraphQL. No gRPC. No tRPC. (Other skills exist.)
• No database schema design (use a DB skill).
• No auth implementation (that's a separate skill; this one leaves a clear hook).
• No deployment scripts (that's the deployment category).
• No framework migration (does not convert Express → Fastify).

Security

• Scope: operates within the target project directory only. Refuses paths with .. or absolute paths outside the project root.
• No silent network calls. Package installs use the user's local registry; no curl | sh, no vendored binaries. Confirms before running any pnpm install.
• No env exfiltration. Never reads ~/.ssh, ~/.aws, .env from other projects, or shell history. The .env.example file generated has placeholders only.
• Destructive confirm. Before overwriting any existing file (including package.json, tsconfig.json), prints a diff and asks for y/N.
• Least-privilege allowed-tools: Read, Write, Edit, Glob, Grep, Bash(pnpm *), Bash(npm *), Bash(node *). No WebFetch, no WebSearch.
• Secure defaults in generated code: helmet on, CORS origin list (never * in prod), rate limiter on, error handler that never leaks stack traces, logger that never logs bodies or auth headers.
• Dependencies: pinned exact versions in generated package.json. Documents that pnpm audit should be run before shipping.