NestJS Backend API Development Skill

Knowledge Freshness

This skill is based on the NestJS documentation homepage, first steps guide, controllers guide, providers guide, configuration technique guide, and nestjs/nest repository reviewed on 2026-06-04. The official @nestjs/core package metadata was also checked on the same date and reported version 11.1.24, MIT licensing, and the canonical nestjs/nest repository.

Prefer the live NestJS docs and official repository over model memory for current CLI commands, package names, module conventions, HTTP adapter behavior, dependency-injection rules, testing helpers, configuration patterns, validation guidance, and migration notes.

Retrieval Sources

• https://docs.nestjs.com/
• https://docs.nestjs.com/first-steps
• https://docs.nestjs.com/controllers
• https://docs.nestjs.com/providers
• https://docs.nestjs.com/techniques/configuration
• https://github.com/nestjs/nest

Scope Note

Use this skill for NestJS backend API work: module design, controllers, providers, dependency injection, configuration, request validation, guards, interceptors, filters, testing, OpenAPI docs, and production review. It is not a generic Node.js API guide, not a Hono edge API skill, not a FastAPI skill, and not a database-specific ORM guide.

Core Workflow

1. Inventory the service: NestJS version, Node.js version, package manager, TypeScript config, app entry point, HTTP adapter, deployment target, module layout, test runner, and existing global pipes, guards, interceptors, and filters.
2. Confirm the intended service boundary. Identify whether the work is a new app, feature module, controller addition, provider refactor, migration from Express/Fastify, or production-hardening pass.
3. Map the API contract before coding: routes, methods, params, query strings, request bodies, response DTOs, error shapes, auth requirements, versioning, rate limits, idempotency needs, and backward-compatibility constraints.
4. Design modules deliberately. Keep imports, exports, providers, dynamic modules, and shared modules explicit so the dependency graph remains clear.
5. Add or update controllers with thin request handling. Keep transport-specific parsing, auth decisions, DTO validation, and response mapping close to the controller, but move business behavior into providers.
6. Add providers for application logic and integration boundaries. Prefer constructor injection, explicit interfaces where useful, and testable service methods over hidden globals.
7. Define DTOs and validation rules. Review required fields, optional fields, nested objects, arrays, enum behavior, transforms, defaults, and how invalid payloads are reported.
8. Configure validation pipes intentionally. For global pipes, review whitelist, forbidNonWhitelisted, transform, nested validation, and compatibility with existing clients.
9. Add guards, interceptors, filters, and middleware only where their scope is clear. Confirm route matching, public-route exceptions, admin boundaries, error mapping, logging behavior, and performance impact.
10. Wire configuration through approved environment handling. Validate required values at startup, avoid client-exposed secrets, and document local, staging, CI, and production differences.
11. Add OpenAPI docs when useful. Review generated schemas, auth schemes, examples, deprecated routes, and hidden/internal fields before publishing documentation.
12. Test the module. Cover provider unit tests, controller or module integration tests, e2e HTTP flows, failure cases, validation failures, auth denials, and external-service boundaries with mocks or test doubles.
13. Review production behavior: startup errors, graceful shutdown, health checks, structured logging, tracing, timeouts, retries, database transactions, message handlers, cron jobs, queues, and rollback.
14. Produce a concise implementation summary with changed files, API contract changes, validation behavior, auth impact, test coverage, deployment notes, and remaining risks.

Required Inputs

• NestJS version, Node.js version, package manager, TypeScript settings, app entry point, HTTP adapter, deployment provider, and build command.
• Existing module tree, controller routes, providers, middleware, global pipes, guards, interceptors, filters, and test setup.
• API contract requirements: route paths, methods, request DTOs, response DTOs, error shape, auth model, versioning, client compatibility, and OpenAPI needs.
• Configuration model for environment variables, secrets, validation, local development, CI, preview, staging, and production.
• External dependencies such as databases, queues, caches, webhooks, OAuth providers, third-party APIs, observability, and feature flags.
• Migration or rollback constraints for existing routes, clients, database schema, deployed workers, background jobs, and scheduled tasks.

Production Rules

• Keep controllers thin and providers testable. When a controller starts owning business logic, move that behavior into a provider and test it there.
• Treat module imports and provider exports as an API. Avoid broad shared modules that hide coupling or make circular dependencies harder to detect.
• Do not make validation global until existing clients and error handling have been checked. Stricter DTO rules can break integrations that send extra or loosely typed fields.
• Treat guards and interceptors as security-sensitive. Every public route, admin route, webhook route, and machine-to-machine endpoint needs an explicit expected outcome.
• Never log secrets, bearer tokens, cookies, raw passwords, refresh tokens, full OAuth payloads, or complete customer request bodies.
• Review OpenAPI output before publishing it. Generated schemas can expose internal fields, examples, route names, auth details, or undocumented admin surfaces.
• Prefer explicit timeout, retry, and idempotency behavior around external calls, queues, cron jobs, and webhooks. A provider method that works locally can still duplicate work under retry or deployment restarts.
• Use e2e tests for the real HTTP behavior that clients rely on: route matching, validation errors, auth denials, response shapes, headers, and status codes.

Validation Checklist

• Package install and build commands match the project package manager.
• main.ts bootstraps the intended app module and applies reviewed global pipes, filters, guards, interceptors, and middleware.
• Modules import and export only what downstream modules require.
• Controllers declare route paths, methods, DTOs, status codes, and exception behavior deliberately.
• Providers isolate business logic and external-service access behind testable methods.
• DTO validation covers required fields, optional fields, nested objects, arrays, enums, transforms, and rejected unknown fields.
• Configuration fails fast for missing required values without printing secrets.
• OpenAPI docs hide internal fields and accurately describe auth, request, and response behavior.
• Unit, integration, and e2e tests cover happy paths, validation failures, authorization failures, and representative external-service errors.
• Deployment notes cover environment variables, health checks, graceful shutdown, migrations, observability, rollback, and incident recovery.

Troubleshooting

Dependency injection error at startup

Inspect the failing provider token, module imports, module exports, circular dependencies, and dynamic module configuration. Confirm the provider is declared in the module that owns it and exported only when another module needs it.

Validation accepts or rejects the wrong payload

Check DTO decorators, optional fields, nested validation setup, arrays, transform behavior, whitelist, forbidNonWhitelisted, and whether a global pipe is overriding route-level expectations.

Guard blocks a public route

Review the guard scope, route metadata, public-route decorator, global guard registration, controller inheritance, and test coverage for public, private, admin, and webhook routes.

OpenAPI docs show internal fields

Review DTO classes, example values, hidden properties, response decorators, auth decorators, route grouping, and whether internal admin controllers are included in the published document.

E2E tests pass locally but fail in CI

Check environment variables, database lifecycle, port binding, test app module configuration, external-service mocks, timeouts, fake timers, and whether tests share mutable state across files.

Duplicate Check

This entry was checked against the current upstream/main content tree and open pull requests before drafting. Existing content only mentions NestJS in a backend collection and a command example; no dedicated content/skills, content/agents, content/hooks, or content/mcp entry matches NestJS, @nestjs/core, docs.nestjs.com, or nestjs/nest.

Editorial Disclosure

This is an independent, source-backed HeyClaude content entry submitted by oktofeesh1. It is not sponsored by NestJS, the NestJS maintainers, or OpenJS-style ecosystem projects. The linked source archive is the official upstream repository archive and is not repackaged or verified by HeyClaude.