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

Input	Why
Service name	Package name, log `service` field, Docker image tag
Framework ADR	Fastify 5 vs NestJS 11 vs Express 5
Port default	`3000` or platform convention
Data dependencies	Postgres, Redis, none day one
Monorepo path	`services/orders-api` vs root repo

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

"type": "module" unless ADR mandates CommonJS.
No secrets in generated files - placeholders in .env.example only.
Health route before domain routes - load balancers need it day one.
Pino JSON logging - no console.log in production paths.
Graceful shutdown - SIGTERM closes server and DB pool.
Do not add ORM until ADR specifies - stub repository interface is OK.
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 -sf http://localhost:3000/health
curl -sf http://localhost:3000/ready

# 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 app.register(healthRoutes);
  return app;
}

// 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" });
  await app.close();
  process.exit(0);
};
 
process.on("SIGTERM", close);
process.on("SIGINT", close);
 
await app.listen({ port: env.PORT, host: "0.0.0.0" });

# 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
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

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

Fastify or Nest for every new service?

Fastify for small IO-bound APIs. Nest when the team needs DI, modules, and GraphQL guards at day one. Follow the org ADR - skill does not decide alone.

Include Prisma in scaffold?

Only when input says ORM ADR accepted. Otherwise stub UserRepository interface and add ORM in a follow-up PR.

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.

API Scaffold Skill

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

What This Skill Does

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

Input	Why
Service name	Package name, log `service` field, Docker image tag
Framework ADR	Fastify 5 vs NestJS 11 vs Express 5
Port default	`3000` or platform convention
Data dependencies	Postgres, Redis, none day one
Monorepo path	`services/orders-api` vs root repo

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

"type": "module" unless ADR mandates CommonJS.
No secrets in generated files - placeholders in .env.example only.
Health route before domain routes - load balancers need it day one.
Pino JSON logging - no console.log in production paths.
Graceful shutdown - SIGTERM closes server and DB pool.
Do not add ORM until ADR specifies - stub repository interface is OK.
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 -sf http://localhost:3000/health
curl -sf http://localhost:3000/ready

# 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 app.register(healthRoutes);
  return app;
}

// 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" });
  await app.close();
  process.exit(0);
};
 
process.on("SIGTERM", close);
process.on("SIGINT", close);
 
await app.listen({ port: env.PORT, host: "0.0.0.0" });

# 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
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

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

Fastify or Nest for every new service?

Fastify for small IO-bound APIs. Nest when the team needs DI, modules, and GraphQL guards at day one. Follow the org ADR - skill does not decide alone.

Include Prisma in scaffold?

Only when input says ORM ADR accepted. Otherwise stub UserRepository interface and add ORM in a follow-up PR.

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.

API Scaffold Skill

Search Documentation

API Scaffold Skill