Nestjs

NestJS — progressive Node.js framework

NestJS is a framework for building efficient, scalable server-side Node.js applications. It is TypeScript-first (works with plain JS too), heavily modular, and built around dependency injection. Under the hood it runs on a pluggable HTTP platform — Express (default, @nestjs/platform-express) or Fastify (@nestjs/platform-fastify) — and the same building blocks also power GraphQL, WebSocket, and microservice apps. Its architecture is heavily inspired by Angular: decorators + DI + modules.

This skill is a faithful offline copy of the official NestJS documentation. The narrative below is the map; open the matching file under references/ for exact APIs, options, and full detail. Start navigation at references/CONTENTS.md. Targets NestJS v11; the live docs are at https://docs.nestjs.com.

Mental model — three building blocks

1. Modules organize the app. Every app has a root AppModule; features get their own module. A @Module({ imports, controllers, providers, exports }) declares what it owns and what it shares. → references/modules.md.
2. Providers hold logic and are wired by dependency injection. Mark a class @Injectable(), list it in a module's providers, and inject it via the constructor. Most "services", repositories, factories, and helpers are providers. → references/components.md (providers) and references/fundamentals/dependency-injection.md (custom providers).
3. Controllers handle incoming requests and return responses. Decorators map routes to handler methods. → references/controllers.md.

import { Controller, Get } from '@nestjs/common';
import { CatsService } from './cats.service';

@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {} // DI by type

  @Get()
  findAll() {
    return this.catsService.findAll();
  }
}

import { Module } from '@nestjs/common';

@Module({
  controllers: [CatsController],
  providers: [CatsService],   // available for DI within this module
  exports: [CatsService],     // share with modules that import this one
})
export class CatsModule {}

Setup & the entry point

$ npm i -g @nestjs/cli      # the Nest CLI
$ nest new project-name     # scaffold (asks package manager; --strict for strict TS)
$ nest g resource cats      # generate a CRUD module+controller+service+DTOs

main.ts bootstraps the app with NestFactory:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

→ references/first-steps.md. For a non-HTTP app (CLI/cron/worker), use NestFactory.createApplicationContext → references/application-context.md. The CLI itself: references/cli/overview.md (monorepo workspaces, libraries).

The request pipeline (canonical order)

This is the single most important thing to get right. A request flows through cross-cutting components in a fixed order; globals run, then controller-bound, then route-bound (filters are the exception — they resolve route → controller → global):

1. Middleware — global, then module-bound (Express-style; runs before guards). → references/middlewares.md
2. Guards — authorization/authentication "can this proceed?" → references/guards.md
3. Interceptors (pre) — wrap the handler; can transform/observe. → references/interceptors.md
4. Pipes — validate & transform inputs (params/body/query). → references/pipes.md
5. Route handler — your controller method calls providers.
6. Interceptors (post) — map/observe the response (RxJS, last-in-first-out).
7. Exception filters — only on an uncaught error; format the response. → references/exception-filters.md

Bind any of them at three levels: global (app.useGlobalX() or an APP_* provider token), controller (decorator on the class), or route (decorator on the method). Read the exact ordering rules — especially for pipes & interceptors — in references/faq/request-lifecycle.md. Build your own request-shaped logic with custom decorators and the execution context (ExecutionContext, Reflector for reading metadata set by @SetMetadata).

Dependency injection & fundamentals

DI is resolved by type (the constructor param's class) or by token (@Inject(TOKEN)). A provider is visible only within its module unless exports-ed and the consumer's module imports it.

• Custom providers — useClass / useValue / useFactory (with inject) / useExisting, and non-class tokens. → references/fundamentals/dependency-injection.md
• Async providers — useFactory returning a Promise (e.g. wait for a DB connection). → references/fundamentals/async-components.md
• Dynamic modules — Module.forRoot()/forFeature() configurable modules. → references/fundamentals/dynamic-modules.md
• Injection scopes — DEFAULT (singleton), REQUEST, TRANSIENT. Request scope has a perf cost and bubbles up. → references/fundamentals/provider-scopes.md
• Circular dependency — break with forwardRef(). → references/fundamentals/circular-dependency.md
• Module reference — resolve providers imperatively with ModuleRef. → references/fundamentals/module-reference.md
• Lifecycle hooks — OnModuleInit, OnApplicationBootstrap, OnModuleDestroy, OnApplicationShutdown (enable shutdown hooks for the last). → references/fundamentals/lifecycle-events.md
• Also: lazy-loading modules, discovery service, platform agnosticism.

Validation, configuration & databases

• Validation — the global ValidationPipe + class-validator/class-transformer decorators on DTOs (whitelist, transform, forbidNonWhitelisted). → references/techniques/validation.md
• Configuration — @nestjs/config ConfigModule.forRoot() + ConfigService, .env, validation schema, namespaced config. → references/techniques/configuration.md
• SQL (TypeORM / Sequelize) — @nestjs/typeorm, forRoot/forFeature, repositories, entities. → references/techniques/sql.md · recipes: TypeORM, Sequelize, Prisma, MikroORM.
• MongoDB (Mongoose) — @nestjs/mongoose, schemas, models. → references/techniques/mongo.md

More techniques

Caching · Queues / BullMQ · Task scheduling / cron · Events · Logger · Serialization (ClassSerializerInterceptor) · Versioning · File upload · Streaming files · Server-Sent Events · Cookies · Sessions · Compression · HTTP module (HttpService/axios) · MVC · Performance (Fastify).

Security

Authentication (Passport strategies, JWT, @nestjs/passport/@nestjs/jwt; full Passport recipe: references/recipes/passport.md) · Authorization (RBAC, claims, CASL) · Rate limiting (@nestjs/throttler) · Helmet · CORS · CSRF · Encryption & hashing. Auth is typically a guard; authorization combines a guard with metadata read via Reflector.

GraphQL, WebSockets & microservices

• GraphQL — @nestjs/graphql with the Apollo (or Mercurius) driver; code-first (decorators + generated SDL) or schema-first. Resolvers, mutations, subscriptions, federation. → references/graphql/quick-start.md and the rest of references/graphql/.
• WebSockets — @WebSocketGateway() gateways (socket.io or ws), with the same guards/pipes/interceptors/filters model. → references/websockets/gateways.md.
• Microservices — @nestjs/microservices; choose a transporter (TCP, Redis, NATS, MQTT, RabbitMQ, Kafka, gRPC) and use @MessagePattern (request-response) vs @EventPattern (event). → references/microservices/basics.md and the per-transport pages.

OpenAPI, testing & deployment

• OpenAPI / Swagger — @nestjs/swagger SwaggerModule, @ApiProperty() etc., and the CLI plugin that auto-infers schemas. → references/openapi/introduction.md.
• Testing — @nestjs/testing Test.createTestingModule(...), .overrideProvider(...), unit + e2e (supertest). → references/fundamentals/unit-testing.md · Automock/Suites.
• Deployment → references/deployment.md; serverless → references/faq/serverless.md; Devtools graph → references/devtools/overview.md.

Recipes

Task-oriented guides: references/recipes/ — CRUD generator, REPL, CQRS, SWC builder, hot reload, health checks (Terminus), Sentry, serve-static, router module, nest-commander, async local storage, Compodoc, and more. Browse references/CONTENTS.md.

Gotchas

• "Nest can't resolve dependencies of X" — the dependency isn't a provider in the current module, or its owning module doesn't exports it and isn't imports-ed. Check the module graph first. → references/faq/errors.md
• Decorators need TS config — experimentalDecorators + emitDecoratorMetadata, and reflect-metadata imported once. DI by type relies on emitted metadata.
• Global pipes/guards/etc. set via app.useGlobalX() can't inject — to use DI in a global, register it as an APP_PIPE / APP_GUARD / APP_INTERCEPTOR / APP_FILTER provider instead.
• ValidationPipe does nothing useful without DTOs decorated with class-validator, and needs transform: true to instantiate DTO classes / coerce types. Use whitelist to strip unknown props.
• Circular imports/providers — use forwardRef() on both sides; prefer restructuring.
• Request-scoped providers make the whole injection chain request-scoped — measurable overhead; keep them shallow.
• Pipe & interceptor binding order is not simply top-to-bottom — parameter pipes resolve last-param-to-first; read references/faq/request-lifecycle.md.
• Keep @nestjs/* versions aligned (core/common/platform and the ecosystem packages move together across majors). This bundle targets v11.

Provenance

references/ is converted from the official nestjs/docs.nestjs.com content/ source (the same Markdown that powers https://docs.nestjs.com) by tools/build_references.py — the TS/JS @@switch snippets are reduced to their canonical TypeScript form, promo banners are dropped, and links are absolutized to the live site. Every page keeps a > Source: link to its upstream file on GitHub. Redistributed under the upstream MIT license (Kamil Myśliwiec) — see references/LICENSE.