This document provides a high-level introduction to the NestJS framework, its core philosophy, architectural principles, and repository organization. It covers the fundamental concepts that define NestJS as a framework and how the codebase is structured to support its design goals.
For detailed information about specific subsystems, see:
NestJS is a progressive Node.js framework for building efficient, scalable server-side applications. The framework is built with TypeScript (while maintaining full compatibility with pure JavaScript) and combines elements of Object-Oriented Programming (OOP), Functional Programming (FP), and Functional Reactive Programming (FRP).
Current Version: 11.1.10
License: MIT
Author: Kamil Myśliwiec
The framework provides an out-of-the-box application architecture that enables developers to create highly testable, scalable, loosely coupled, and maintainable applications. This architectural approach is heavily inspired by Angular, bringing similar patterns and conventions to server-side development.
Sources: package.json1-15 Readme.md24-33
NestJS addresses a fundamental problem in the Node.js ecosystem: while numerous libraries, helpers, and tools exist for Node.js, few effectively solve the architectural challenges of building scalable server-side applications. The framework's philosophy centers on three key principles:
NestJS provides a complete application architecture that solves common structural problems, eliminating the need for developers to piece together disparate libraries and patterns.
Under the hood, NestJS defaults to using Express but provides compatibility with various HTTP server libraries through an adapter pattern. This includes support for Fastify and other platforms, allowing developers to leverage existing third-party plugins from these ecosystems.
The framework brings Angular's proven architectural patterns to the server-side, including:
Sources: Readme.md30-33 packages/platform-express/Readme.md24-33
| Dependency | Version | Purpose |
|---|---|---|
| TypeScript | 5.9.3 | Primary language, provides type safety |
| reflect-metadata | 0.2.2 | Enables decorator-based metadata reflection for DI |
| rxjs | 7.8.2 | Reactive programming support, used throughout framework |
| express | 5.2.1 | Default HTTP server implementation |
| class-transformer | 0.5.1 | Serialization and transformation of DTOs |
| class-validator | 0.14.3 | Validation decorators for DTOs |
Sources: package.json61-81 package.json174-176
The NestJS codebase is organized as a Lerna-managed monorepo containing multiple packages and sample applications. This structure allows for coordinated releases while maintaining separation of concerns.
Core Framework:
@nestjs/core: Contains NestFactory, NestContainer, Injector, and application lifecycle management@nestjs/common: Provides decorators (@Controller, @Injectable, @Module), HTTP utilities, and exceptionsPlatform Adapters:
@nestjs/platform-express: Express.js integration (default)@nestjs/platform-fastify: Fastify integration for high-performance applicationsReal-Time Communication:
@nestjs/websockets: Abstract WebSocket gateway layer@nestjs/platform-ws: Native ws library adapter@nestjs/platform-socket.io: Socket.IO adapterDistributed Systems:
@nestjs/microservices: Supports RabbitMQ, Kafka, Redis, NATS, MQTT, and gRPC transportsDevelopment Tools:
@nestjs/testing: Utilities for creating test modules and mocking dependenciesSources: package.json1-3 High-level diagrams
The repository contains 30+ sample applications demonstrating various integration patterns and use cases:
| Category | Samples | Purpose |
|---|---|---|
| Database Integration | 05-sql-typeorm, 06-mongoose, 07-sequelize, 13-mongo-typeorm, 14-mongoose-base, 22-graphql-prisma | SQL/NoSQL database patterns |
| API Patterns | 11-swagger, 12-graphql-schema-first, 23-graphql-code-first | REST and GraphQL APIs |
| Real-Time | 02-gateways, 16-gateways-ws, 28-sse | WebSockets and Server-Sent Events |
| Microservices | 03-microservices, 04-grpc | Distributed system patterns |
| Features | 19-auth-jwt, 20-cache, 26-queues, 27-scheduling, 29-file-upload | Authentication, caching, queues, scheduling |
Each sample includes its own package.json with dependencies, demonstrating how to integrate specific technologies with NestJS.
Sources: sample/06-mongoose/package.json1-71 sample/22-graphql-prisma/package.json1-67 sample/12-graphql-schema-first/package.json1-92 sample/23-graphql-code-first/package.json1-60
The fundamental organizational unit in NestJS. Modules use the @Module() decorator to define their structure and are managed by the DependenciesScanner in @nestjs/core.
Handle incoming HTTP requests using decorators like @Controller(), @Get(), @Post(). Controllers are registered and resolved by the routing system.
Injectable classes decorated with @Injectable() that can be managed by the Injector and NestContainer. This includes services, repositories, factories, and helpers.
A layered pipeline for request processing:
MiddlewareModule)Sources: High-level diagrams, package.json1-242
tsc -b packages for efficient incremental compilationnpm run build, npm run build:dev (watch mode), npm run build:prodreflect-metadata supportnpm run build: Compile all packagesnpm test: Run unit testsnpm run lint: Lint all packagesnpm run format: Format codenpm run publish: Build and publish all packages to npmSources: package.json16-51 package.json82-173 package.json194-241
NestJS achieves platform agnosticism through the AbstractHttpAdapter pattern:
Express (Default):
Fastify:
Both adapters implement the same interface defined by AbstractHttpAdapter, ensuring that application code remains portable across platforms. The adapter handles platform-specific differences in routing, middleware registration, request/response handling, and static file serving.
Sources: High-level diagrams, package.json67 package.json82 package.json131
NestJS packages are published to npm under the @nestjs scope. A typical installation includes:
Sources: Readme.md35-56 package.json6-13
Refresh this wiki