API Scaffold Skill

Fastify/Nest bootstrap with tests and Dockerfile - an Agent Skill for new Node.js 24 TypeScript services.

What This Skill Does

Produces an executable scaffold checklist: folder layout, package.json scripts, health endpoint, structured logging, graceful shutdown, Dockerfile, and GitHub Actions job stub aligned with team CI.

When to Invoke

• New microservice in a monorepo or standalone repo
• Replacing a script-only prototype with a deployable API
• Splitting a monolith bounded context into its own service
• Standardizing a hackathon repo before production hardening

Inputs

Outputs

• Directory tree with src/, test/, Dockerfile
• package.json scripts: dev, build, start, typecheck, test
• /health and /ready routes (ready checks DB if configured)
• .env.example with Zod-validated env module stub
• .github/workflows/pr-checks.yml excerpt using same scripts
• Verification command block

Guardrails

1. "type": "module" unless ADR mandates CommonJS.
2. No secrets in generated files - placeholders in .env.example only.
3. Health route before domain routes - load balancers need it day one.
4. Pino JSON logging - no console.log in production paths.
5. Graceful shutdown - SIGTERM closes server and DB pool.
6. Do not add ORM until ADR specifies - stub repository interface is OK.
7. engines.node pinned to 24.18.0.

Recipe

Quick-reference recipe card - copy-paste ready.

# After skill output - verification sequence
cd services/billing-api
npm ci
npm run typecheck
npm test
npm run build
docker build -t billing-api:local .
docker run --rm -p 3000:3000 --env-file .env.example billing-api:local &
curl

# Expected tree (Fastify 5)
billing-api/
├── src/
│   ├── app.ts          # buildApp() factory
│   ├── server.ts       # listen + shutdown
│   ├── env.ts          # Zod parse process.env
│   └── routes/
│       └── health.ts
├── test/
│   └── health.test.ts  # node:test + inject
├── Dockerfile
├── package.json
├── tsconfig.json
└── .env.example

Working Example (Fastify 5)

// src/app.ts
import Fastify from "fastify";
import { healthRoutes } from "./routes/health.js";
 
export async function buildApp() {
  const app = Fastify({
    logger: { level: process.env.LOG_LEVEL ?? "info" },
  });
  await

// src/server.ts
import { buildApp } from "./app.js";
import { env } from "./env.js";
 
const app = await buildApp();
 
const close = async () => {
  app.log.info({ event: "shutdown" });

# Dockerfile
FROM node:24.18.0-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:24.18.0-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev

NestJS Variant

When ADR selects NestJS 11:

• Use @nestjs/cli scaffold with strict TS
• Include main.ts with enableShutdownHooks()
• Add @nestjs/terminus health module
• Same verification commands; swap inject for supertest against INestApplication

See NestJS Basics for human-readable depth.

Example Prompts

Use API Scaffold Skill for service "inventory-api":
- Fastify 5, port 3001
- Postgres via DATABASE_URL in .env.example
- Monorepo path: services/inventory-api
- Include GitHub Actions: npm ci, typecheck, test, audit

FAQs

Related

• Agent Skills Basics - skill anatomy
• Fastify Basics - framework concepts
• Testing Fastify Apps - inject tests
• Zod & env-schema Validation - env module

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.