Building a Claude Code Plugin for Your API Stack

weldev-nest-api-toolkit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── nestjs-conventions/
│   │   └── SKILL.md
│   ├── api-testing/
│   │   └── SKILL.md
│   ├── docker-build/
│   │   └── SKILL.md
│   └── ci-pipeline/
│       └── SKILL.md
└── README.md

{
  "name": "weldev-nest-api-toolkit",
  "description": "Conventions, testing patterns, Docker setup, and CI pipeline for our NestJS API stack",
  "version": "1.0.0",
  "author": {
    "name": "Dan Castro"
  }
}

---
name: nestjs-conventions
description: NestJS module structure, dependency injection, DTOs, and cross-cutting concerns (guards, interceptors, pipes) for our API. Use when creating a new module, adding an endpoint, wiring providers, or reviewing NestJS structure.
---
 
# NestJS Conventions
 
Target: NestJS 11, TypeScript 5.x, Node 22 LTS.
 
## Module structure
 
Organize by feature, not by technical layer. Each feature owns its controller, service, DTOs, and entities.
 
```text
src/
├── main.ts
├── app.module.ts
├── common/            # cross-cutting only: filters, guards, interceptors, pipes, decorators
├── config/            # configuration factories and validation
└── modules/
    ├── users/
    │   ├── dto/
    │   ├── entities/
    │   ├── users.controller.ts
    │   ├── users.service.ts
    │   └── users.module.ts
    └── auth/
        ├── dto/
        ├── guards/
        ├── strategies/
        ├── auth.controller.ts
        ├── auth.service.ts
        └── auth.module.ts
```
 
Rules:
 
- Domain code lives inside its feature module. Only truly shared, business-agnostic code goes in common/. If a helper needs to know what a "user" or an "order" is, it does not belong in common/.
- Keep DTOs next to the module that owns them.
- Export a provider from a module only when another module actually consumes it.
 
## Dependency injection
 
- Inject through the constructor with private readonly. Do not instantiate services with new inside other services.
- Depend on abstractions for anything external (database, HTTP clients, queues). Put ORM/repository code behind a provider that speaks domain language.
- Controllers coordinate HTTP, services own business logic. A controller should not orchestrate a multi-step write directly; that belongs in a service that owns the unit of work.
- Prefer one operation per service method (use-case style) over a single service with fifteen unrelated methods.
 
## DTOs and validation
 
Every request body and query gets a DTO validated with class-validator.
 
```ts
// dto/create-user.dto.ts
import { IsEmail, IsString, MinLength } from "class-validator";
 
export class CreateUserDto {
  @IsEmail()
  email: string;
 
  @IsString()
  @MinLength(8)
  password: string;
}
```
 
Enable validation globally in main.ts:
 
```ts
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true, // strip properties not in the DTO
    forbidNonWhitelisted: true, // reject requests with unknown properties
    transform: true, // coerce payloads to DTO instances and primitive types
  }),
);
```
 
whitelist: true matters for security: without it, unexpected fields pass straight through to your service. Whatever global pipes and filters main.ts sets, the integration tests must set the same ones, or tests validate the wrong behavior.
 
## Cross-cutting concerns
 
- Guards for authentication and authorization.
- Interceptors for response shaping, logging, and timing. No business logic in an interceptor.
- Pipes for validation and transformation. ValidationPipe covers most cases.
- Exception filters for consistent error responses. Register a global filter so every error leaves the API in the same shape.
 
## Configuration
 
- Use @nestjs/config with a typed configuration factory. Validate environment variables at startup so a missing var fails fast on boot, not at first request.
- Split dev/staging/prod differences inside config factories, not with scattered if (env === 'prod') branches.
 
## Checklist for a new endpoint
 
1. DTO for the request, validated with class-validator.
2. Service method holding the business logic, dependencies injected.
3. Controller method that is thin: validate, delegate, return.
4. Correct HTTP status via @HttpCode() where the default is wrong.
5. Guard applied if the route is protected.
6. Tests: see the api-testing skill.

---
name: api-testing
description: Write unit tests with Vitest and integration tests with Supertest for NestJS controllers and services. Use when adding tests, setting up a module's test suite, reviewing coverage, or debugging failing NestJS tests.
---
 
# API Testing Conventions
 
Stack: Vitest, Supertest, @nestjs/testing. NestJS 11, Node 22.
 
## Required setup (read this first)
 
Vitest transforms TypeScript with esbuild by default, and esbuild does not emit decorator metadata. NestJS resolves constructor dependencies from that metadata, so a NestJS test suite run through plain Vitest fails at DI resolution ("Nest can't resolve dependencies..."). This is the single most common reason NestJS plus Vitest "doesn't work."
 
Fix it by transforming with SWC instead.
 
Install:
 
```bash
npm i -D vitest unplugin-swc @swc/core @types/supertest supertest
```
 
reflect-metadata must be a regular dependency (not devDependencies) and be imported once at the app entry point.
 
vitest.config.ts:
 
```ts
import swc from "unplugin-swc";
import { defineConfig } from "vitest/config";
 
export default defineConfig({
  test: {
    globals: true,
    root: "./",
  },
  plugins: [
    // SWC preserves emitDecoratorMetadata; esbuild does not.
    swc.vite({ module: { type: "es6" } }),
  ],
});
```
 
If you use tsconfig path aliases, add vite-tsconfig-paths to plugins, before swc.vite.
 
tsconfig.json must have both decorator options on, or SWC has nothing to preserve:
 
```json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
```
 
}
 
## Unit tests (Vitest)
 
Test services and providers in isolation. Mock every injected dependency.
 
- One describe per class, one it per behavior (not per method).
- Never touch a real database or external service in a unit test. If a test needs Prisma or TypeORM, it is an integration test.
- Use Test.createTestingModule only when the class actually depends on the DI container. Otherwise instantiate directly with mocks passed to the constructor. It is faster and the failure output is clearer.
 
```ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { ConflictException } from '@nestjs/common';
import { UsersService } from './users.service';
 
describe('UsersService', () => {
  let service: UsersService;
  const repo = { findByEmail: vi.fn(), create: vi.fn() };
 
  beforeEach(() => {
    vi.clearAllMocks();
    service = new UsersService(repo as any);
  });
```
 
it('rejects a duplicate email', async () => {
repo.findByEmail.mockResolvedValue({ id: '1' });
await expect(
service.create({ email: 'a@b.com', password: 'password123' }),
).rejects.toThrow(ConflictException);
expect(repo.create).not.toHaveBeenCalled();
});
});
 
## Integration tests (Supertest)
 
Boot the full app, then drive it over HTTP.
 
```ts
import { Test } from '@nestjs/testing';
import { INestApplication, ValidationPipe } from '@nestjs/common';
import request from 'supertest';
import { AppModule } from '../src/app.module';
 
describe('Users (e2e)', () => {
  let app: INestApplication;
 
  beforeAll(async () => {
    const moduleRef = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();
 
    app = moduleRef.createNestApplication();
    // Mirror main.ts exactly, or tests pass for the wrong reason.
    app.useGlobalPipes(
      new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }),
    );
    await app.init();
  });
```
 
afterAll(async () => {
await app.close();
});
 
it('POST /users creates a user', async () => {
await request(app.getHttpServer())
.post('/users')
.send({ email: 'a@b.com', password: 'password123' })
.expect(201);
});
 
it('POST /users rejects an invalid payload', async () => {
await request(app.getHttpServer())
.post('/users')
.send({ email: 'not-an-email' })
.expect(400);
});
});
 
Rules:
 
- Apply the same global pipes, filters, and interceptors the real app uses.
- Test the request/response contract: status codes, response shape, validation errors, auth guards. Business-logic edge cases stay in the unit suite.
- Use a disposable test database or reset the schema between test files. Shared mutable state across test files is the top cause of flaky Supertest suites. If you see order-dependent failures, that is the first place to look.
- Always await app.close() in afterAll, or the process hangs and CI times out.
 
## Naming and structure
 
- Unit test files sit next to the source: users.service.spec.ts.
- Integration test files live under test/, named after the resource: test/users.e2e-spec.ts.
- Every new endpoint needs at least one integration test for the happy path and one for a validation failure.
 
## Scripts
 
```json
"scripts": {
  "test": "vitest run",
  "test:watch": "vitest",
  "test:e2e": "vitest run test/**/*.e2e-spec.ts",
  "test:cov": "vitest run --coverage"
}
```

---
name: docker-build
description: Multi-stage Dockerfile and .dockerignore for a production NestJS API, small image, non-root user, correct signal handling, health check. Use when writing or reviewing a Dockerfile, containerizing the API, or debugging image size or container startup.
---
 
# Docker Build (NestJS, production)
 
Goal: a small, reproducible, non-root image that starts fast and shuts down cleanly. A naive FROM node:22 plus COPY . . image is about 1GB; the multi-stage Alpine build below lands around 150 to 200MB.
 
## Multi-stage Dockerfile
 
```dockerfile
# syntax=docker/dockerfile:1
 
# ---------- build ----------
# Pin a specific patch in real deployments (e.g. node:22.11.0-alpine) so a
# Node patch release is never introduced silently on a rebuild.
FROM node:22-alpine AS build
WORKDIR /app
 
# Copy lockfile first so the dependency layer only rebuilds when deps change.
COPY package.json package-lock.json ./
RUN npm ci
 
COPY tsconfig*.json nest-cli.json ./
COPY src ./src
RUN npm run build
 
# ---------- production dependencies ----------
FROM node:22-alpine AS prod-deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
 
# ---------- runtime ----------
FROM node:22-alpine AS runner
ENV NODE_ENV=production
WORKDIR /app
 
# tini reaps zombies and forwards SIGTERM so NestJS shuts down gracefully.
RUN apk add --no-cache tini
 
# Run as the unprivileged node user that the official image already ships.
COPY --chown=node:node --from=prod-deps /app/node_modules ./node_modules
COPY --chown=node:node --from=build /app/dist ./dist
COPY --chown=node:node package.json ./
USER node
 
EXPOSE 3000
 
# Requires a /health endpoint (see @nestjs/terminus).
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget --quiet --tries=1 --spider http://localhost:3000/health || exit 1
 
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "dist/main.js"]
```
 
## .dockerignore
 
Without this, node_modules, .git, and .env get baked into the image and invalidate the build cache on every change.
 
```text
node_modules
dist
npm-debug.log
.git
.gitignore
.env
.env.*
*.md
.github
.vscode
coverage
Dockerfile
.dockerignore
```
 
## Why each choice
 
- npm ci, not npm install: deterministic, honors the lockfile, fails if package.json and the lockfile disagree.
- Separate prod-deps stage: the runtime image gets production dependencies only. TypeScript, the Nest CLI, and test tooling never reach the final layer.
- Non-root USER node: a compromised process runs unprivileged. The official Node image already provides this user.
- NODE_ENV=production: many libraries skip dev-only work when it is set.
- tini as PID 1: node (and worse, npm start) as PID 1 does not forward SIGTERM properly, so docker stop waits, then kills the process mid-request. tini (or docker run --init) fixes graceful shutdown. Pair it with app.enableShutdownHooks() in main.ts.
- CMD node dist/main.js, not npm run start:prod: one fewer process in the tree and clean signal handling.
 
## Gotchas
 
- Alpine uses musl, not glibc. Prebuilt native modules (bcrypt, sharp, node-canvas) can break. Either compile from source or switch the base to node:22-slim (Debian-slim, glibc, about 250MB).
- Cross-architecture builds. Building on Apple Silicon (arm64) and deploying to x86_64 without --platform=linux/amd64 produces an image the target can't run. Use docker buildx in CI.
- Pin the base image in production so Node patch releases are deliberate, not silent.

---
name: ci-pipeline
description: GitHub Actions workflow for the NestJS API, lint, unit tests, build, integration tests, and image push in the right order. Use when creating or reviewing a CI workflow, adding a pipeline stage, or debugging a failing GitHub Actions run.
---
 
# CI Pipeline (GitHub Actions)
 
Order, fastest-failing first: lint, then unit tests, then build, then integration tests, then image build and push. Cheap checks gate expensive ones, so a lint error never waits on a Docker build.
 
## Workflow
 
```yaml
# .github/workflows/ci.yml
name: CI
 
on:
  push:
    branches: [main]
  pull_request:
 
# Cancel superseded runs on the same ref (e.g. rapid pushes to a PR).
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true
 
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npx tsc --noEmit # type errors fail here, not at build time
 
  unit:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run test:cov
 
  integration:
    runs-on: ubuntu-latest
    needs: unit
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: test
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U test"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    env:
      DATABASE_URL: postgres://test:test@localhost:5432/test
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run test:e2e
 
  docker:
    runs-on: ubuntu-latest
    needs: integration
    # Only build and push the image after a merge to main.
    if: github.ref == 'refs/heads/main'
    permissions:
      contents: read
      packages: write # required to push to GHCR
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: |
            ghcr.io/${{ github.repository }}:latest
            ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
```
 
## Why each choice
 
- cache: npm on setup-node caches the npm store keyed on the lockfile. Do not hand-roll actions/cache for this.
- npm ci in every job for a reproducible install from the lockfile.
- tsc --noEmit in lint catches type errors early and cheaply. SWC-based builds skip type checking, so without this a type error surfaces later, or never.
- needs: chaining enforces the fail-fast order.
- services: postgres gives integration tests a real database on localhost:5432, health-gated so tests don't start before it's ready. Match production's major version.
- if: github.ref == 'refs/heads/main' on the image job builds and pushes only after merge, not on every PR.
- permissions: packages: write is required for GHCR pushes; the default token is read-only for packages otherwise.
- cache-from/to: type=gha reuses Docker layer cache across runs.

claude --plugin-dir ./weldev-nest-api-toolkit

/weldev-nest-api-toolkit:api-testing

/plugin marketplace add your-org/deelvw - nest - api - toolkit;

/plugin install weldev-nest-api-toolkit@your-org
/reload-plugins

/weldev-nest-api-toolkit:ci-pipeline