nestjs-api

Iron Law

NO NESTJS MODULE WITHOUT READING reference/nestjs-conventions.md FIRST — Fastify adapter quirks, Prisma 7.x patterns, and DTO validation rules are defined there

NestJS 11.x + Fastify + Prisma REST API Skill

Conventions & Rules

For code conventions, package layout, NestJS rules, Prisma 7.x rules, and environment file rules, read reference/nestjs-conventions.md

Quick Scaffold — New NestJS Project

# Using NestJS CLI
npx @nestjs/cli new my-service --package-manager npm --strict

Process

1. Scaffold using NestJS CLI or the command above
2. Configure package.json and tsconfig — read reference/nestjs-config-basics.md, reference/nestjs-config-npm-ts.md, and reference/nestjs-config-prisma7.md
3. Create files using templates — read reference/nestjs-templates-core.md for main.ts, AppModule, CoreModule; read reference/nestjs-templates-features.md for feature modules, controllers, services, DTOs
4. Follow conventions below for package layout and NestJS rules
5. Write tests with Vitest + supertest or NestJS Testing utilities
6. Format and check: npm run lint && npm run typecheck

Key Patterns

| Pattern | Implementation | |---------|---------------| | Modules | @Module() with imports/providers/exports, aggregation pattern | | Controllers | @Controller('api/v1/...') with route decorators | | Services | @Injectable() with constructor injection | | DTOs | Classes with class-validator decorators (@IsString(), @IsNotEmpty()) | | Repositories | Prisma Client via DatabaseService wrapper | | Error handling | @Catch() exception filter returning ProblemDetail (RFC 9457) | | Config | Fail-fast registerAs() with static config reader | | Migrations | Prisma Migrate in prisma/migrations/ | | Guards | @UseGuards() for auth (JwtAuthGuard, RolesGuard) | | Interceptors | LoggingInterceptor, TransformInterceptor (global) | | Pipes | Global ValidationPipe with whitelist and transform |

Reference Files

| File | Content | Load When | |------|---------|-----------| | reference/nestjs-config-basics.md | Static config reader, config module aggregation, fail-fast validation | Project setup, initial configuration | | reference/nestjs-config-npm-ts.md | package.json with dependencies, tsconfig.json | Project setup, configuring dependencies | | reference/nestjs-config-prisma7.md | Prisma 7.x schema, prisma.config.ts, PrismaService, .env template | Setting up database, writing Prisma queries | | reference/nestjs-templates-core.md | main.ts, app.module, core.module templates | Bootstrapping app, creating core module | | reference/nestjs-templates-features.md | Feature module, controller, service, DTO templates | Creating modules, controllers, services | | reference/nestjs-templates-infrastructure.md | Dockerfile, docker-compose, Vitest config | Containerizing app, configuring test runner | | reference/nestjs-enterprise-patterns.md | Exception hierarchy, validation pipe, API versioning | Implementing error handling, input validation, API versioning | | reference/nestjs-enterprise-infrastructure.md | Security middleware (Helmet), rate limiting, Swagger, health checks | Adding security headers, rate limiting, API documentation | | reference/nestjs-resilience-circuit-breaker.md | Circuit breaker, retry, timeout, database fallback | Adding resilience patterns, handling service failures | | reference/nestjs-resilience-context.md | Request context with AsyncLocalStorage, correlation IDs | Adding request tracing, correlation IDs | | reference/nestjs-feature-flags.md | Feature flags service, Redis fallback, gradual rollout | Implementing feature flags, gradual rollout | | reference/nestjs-observability.md | OpenTelemetry tracing/metrics, structured logging, cloud logging | Adding observability, structured logging, tracing | | reference/nestjs-messaging-basics.md | BullMQ queues, background job processing | Adding background jobs, queue processing | | reference/nestjs-messaging-queues.md | RabbitMQ reliable messaging, dead letter queues | Implementing RabbitMQ messaging, dead letter queues | | reference/nestjs-messaging-streaming.md | Kafka event streaming, high-throughput patterns | Implementing Kafka streaming, high-throughput events | | reference/nestjs-testing-unit-basics.md | Unit testing with Vitest, service test patterns | Writing unit tests for services | | reference/nestjs-testing-unit-controllers.md | Controller unit tests, test data factories | Writing unit tests for controllers | | reference/nestjs-testing-unit-mocks.md | Prisma/Redis/HTTP mocking, ConfigService mocking | Mocking dependencies in unit tests | | reference/nestjs-testing-integration-setup.md | E2E testing setup, Testcontainers, supertest | Writing integration tests, E2E tests | | reference/nestjs-testing-integration-patterns.md | Auth testing, validation, pagination patterns | Testing auth flows, pagination, validation | | reference/nestjs-testing-patterns.md | Circuit breaker testing, AsyncLocalStorage testing | Testing resilience patterns, context propagation | | reference/nestjs-testing-ci-troubleshooting.md | Coverage standards, CI/CD, troubleshooting | Configuring CI pipelines, coverage thresholds | | reference/nestjs-rest-workflow.md | REST workflow, OpenAPI/Swagger controller setup | Designing REST endpoints, setting up Swagger | | reference/nestjs-rest-dto-pagination.md | DTO mapping, pagination, filter patterns | Creating DTOs, implementing pagination | | reference/nestjs-rest-upload-errors.md | File uploads, API versioning, ProblemDetail errors | Implementing file uploads, error responses | | reference/nestjs-rest-services.md | Service patterns, external API clients, bulk operations, soft delete | Writing service logic, calling external APIs | | reference/nestjs-security-auth.md | JWT authentication (RS256), password hashing, token management | Implementing JWT auth, implementing guards | | reference/nestjs-security-scanning.md | OWASP scanning, security headers, static analysis | Security auditing, dependency scanning | | reference/nestjs-security-validation-logging.md | Input validation, PII masking, Prisma security | Securing input handling, masking sensitive data | | reference/nestjs-debugging-logging.md | Debug mode, Prisma query logging, Fastify lifecycle | Debugging requests, tracing Prisma queries | | reference/nestjs-debugging-context-di.md | AsyncLocalStorage context, DI debugging, config | Debugging DI issues, context propagation | | reference/nestjs-debugging-performance.md | Memory leaks, performance profiling | Diagnosing memory leaks, profiling performance | | reference/nestjs-debugging-production.md | Production debugging, structured logging, tracing | Debugging production issues, structured logging | | reference/nestjs-review-checklist.md | NestJS review checklist (used by nestjs-reviewer agent) | Code review, pre-PR checklist | | reference/nestjs-real-world-issues.md | 9 framework-level issues from GitHub/SO with frequency ratings and Vitest-adapted solutions | Debugging DI errors, circular deps, JWT config, memory leaks | | reference/nestjs-decision-trees.md | Decision trees for module organization, auth method, testing strategy, caching, error responses | Architecture decisions before implementation |

Common Commands

npm run start:dev                           # Run in dev mode (watch)
npm test                                    # Run unit tests (Vitest)
npm run test:e2e                            # Run integration/E2E tests
npm run test:cov                            # Run tests with coverage report
npm run lint                                # ESLint check
npm run typecheck                           # TypeScript type-check only
npm run build                               # Compile TypeScript
npx prisma migrate dev --name <migration>   # Create and run migration
npx prisma generate                         # Regenerate Prisma client after schema change
npx prisma studio                           # Open Prisma Studio GUI

Documentation Sources

Before generating code, consult these sources for current syntax and APIs:

| Source | URL / Tool | Purpose | |--------|-----------|---------| | Prisma ORM | https://www.prisma.io/docs/llms.txt | Prisma schema, migrations, client API | | NestJS / TypeScript | Context7 MCP | Latest NestJS decorators, modules, patterns |

Error Handling

Validation errors: Use class-validator decorators on DTO classes. Global ValidationPipe auto-returns 422 with details.

Not-found errors: Throw NotFoundException from services. Global exception filter returns structured 404.

Duplicate errors: Catch Prisma P2002 unique constraint violation and convert to 409 Conflict.

Hard Prohibitions

• No raw any request bodies — all endpoints must use DTOs with class-validator decorators
• No raw SQL unless performance-critical (document why in a comment)
• No jest in new code — use Vitest exclusively
• @UseGuards(JwtAuthGuard) on every non-public route — no exceptions
• No arbitrary Tailwind values (p-[13px]) — use the scale (p-4, gap-6)
• Angular: no *ngIf/*ngFor — use @if/@for/@switch; typed reactive forms FormGroup<T> only

Post-Code Review

After writing TypeScript code, dispatch these reviewer agents:

• nestjs-reviewer — module correctness, Prisma usage, resilience patterns
• code-reviewer — general quality, DRY, error handling
• security-reviewer — auth, input validation, OWASP Top 10