Nest.JS

Quick Reference#

TopicFileModule system, circular deps, dynamic modulesmodules.mdDI, providers, injection scopes, custom providersdependency-injection.mdControllers, routing, request lifecyclecontrollers.mdGuards, pipes, interceptors, middleware, filterslifecycle.mdDTOs, validation, transformationvalidation.mdDatabase integration (TypeORM, Prisma, Mongoose)database.mdTesting: unit, integration, e2etesting.mdMicroservices, queues, events, WebSocketsmicroservices.mdConfig, environment, secrets managementconfig.mdPerformance, caching, serializationperformance.md

NestJS vs Plain Node.js — Key Differences#

NestJS builds on Node.js/Express (or Fastify) but introduces an opinionated architecture. The main things that catch people:

• Everything is a class with decorators — @Module, @Controller, @Injectable are not optional annotations, they drive the DI container and module graph.
• Module boundaries matter — a provider is NOT globally available unless explicitly exported and imported. This is the #1 source of "Nest can't resolve dependency" errors.
• Request lifecycle is layered — Middleware → Guards → Interceptors (before) → Pipes → Handler → Interceptors (after) → Exception Filters. Order matters and each layer has a distinct job.
• TypeScript is assumed — decorators, metadata reflection ( reflect-metadata), and emitDecoratorMetadata are load-bearing. Misconfigured tsconfig.json breaks DI silently.

Critical Traps#

• @Injectable() missing — class won't be in DI container, cryptic "resolve dependency" error
• Provider not in module's providers array — same error, different cause
• Provider not exports ed — importing module can't see it, even though the module is imported
• Circular module dependency — use forwardRef(() => ModuleClass) on BOTH sides
• Circular provider injection — use forwardRef(() => ServiceClass) + @Inject(forwardRef(...))
• @Body() empty — missing Content-Type: application/json header or body-parser not configured
• Validation not firing — forgot app.useGlobalPipes(new ValidationPipe()) or missing class-transformer
• Guard returning false silently → 403 — no error message by default, must throw specific exception
• @Res() used → Nest loses response control — use @Res({ passthrough: true }) or avoid @Res()
• Exception filter not catching — filter bound to wrong scope (method vs controller vs global)
• onModuleInit / onModuleDestroy — lifecycle hooks only fire if class is @Injectable() AND in providers
• ConfigService.get() returns undefined — env var not in .env or ConfigModule not imported in that module
• Fastify adapter — Express middleware won't work, must use Fastify equivalents