NestJS — Deep Study

1. Overview / TL;DR

NestJS is a progressive Node.js framework for building efficient, reliable, and scalable server-side applications. It is written in and fully embraces TypeScript, and its architecture is directly inspired by Angular: an opinionated module system, a dependency-injection container, and heavy use of decorators to describe routing, validation, guards, and everything else declaratively. Under the hood it runs on Express by default (Fastify is a drop-in alternative via @nestjs/platform-fastify), so the entire Express middleware ecosystem remains available.

2. Core Architecture — Modules, Controllers, Providers

NestJS is organized around three building blocks. A module groups related controllers (HTTP-facing) and providers (logic + state) into a feature unit. The AppModule is the root that imports everything.

@Module({
  imports: [DatabaseModule],          // other modules this one needs
  controllers: [CatsController],      // route handlers
  providers: [CatsService],           // registered for DI
  exports: [CatsService],             // visible to modules that import CatsModule
})
export class CatsModule {}

@Module({
  imports: [CatsModule, UsersModule, AuthModule],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

3. Dependency Injection — the Engine Under Everything

NestJS implements its own lightweight DI container. Dependencies are declared in the constructor and resolved from the container, never instantiated by hand. This is what makes services unit-testable (you inject mocks) and what keeps the module graph explicit.

@Injectable()
export class CatsService {
  constructor(
    private readonly prisma: PrismaService,   // resolved from CatsModule's providers (or imports)
    @Inject('CONFIG') private readonly config: AppConfig, // custom token
  ) {}
}

Provider syntaxes (custom providers)

Besides a plain class, a provider entry can be an object literal that tells the container how to build the value:

Scopes

• DEFAULT (singleton) — one instance per app, shared everywhere. Default and almost always correct.
• REQUEST — a fresh instance per request (adds allocation overhead; use only for per-request state).
• TRANSIENT — a fresh instance per injection site.

Scope is set via the @Injectable({ scope: Scope.REQUEST }) option or a provider's scope field.

4. Nest CLI & Project Structure

The CLI (@nestjs/cli) scaffolds projects and generates code. 90% of NestJS apps follow the same generated layout, so the structure below is what you'll see in the project you're joining.

src/
├── main.ts               # bootstrap: NestFactory.create + app.listen
├── app.module.ts         # root module — the import tree starts here
├── app.controller.ts     # root controller (usually GET / health)
├── app.service.ts
└── cats/                 # feature module (nest g resource cats)
    ├── cats.module.ts    # @Module wiring controllers + providers
    ├── cats.controller.ts
    ├── cats.service.ts
    ├── dto/              # create-cat.dto.ts, update-cat.dto.ts
    └── entities/         # or schemas/ — data shapes
test/                     # e2e tests (app.e2e-spec.ts)

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix('api');            // every route becomes /api/...
  app.enableCors();                      // CORS for browser clients
  app.useGlobalPipes(new ValidationPipe({ whitelist: true })); // global validation
  await app.listen(3000);
}
bootstrap();

5. Controllers & Request Handling

Controllers are classes with route decorators. Method decorators define the HTTP verb + path; parameter decorators pull values out of the request. Handlers can be async and return objects/arrays directly — Nest serializes them to JSON (or streams via @Res()).

@Controller('cats')                       // base path: /cats
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Get()                                  // GET /cats
  findAll(@Query('age') age?: number) { return this.catsService.findAll(age); }

  @Get(':id')                             // GET /cats/42
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.catsService.findOne(id);  // pipes run before the handler
  }

  @Post()
  @HttpCode(201)                          // default for POST is already 201
  create(@Body() dto: CreateCatDto) { return this.catsService.create(dto); }

  @Delete(':id')
  remove(@Param('id', ParseIntPipe) id: number) { return this.catsService.remove(id); }
}

Parameter decorators cheat sheet

6. Pipes & Validation

A pipe transforms input data before the handler receives it (parse, coerce, default) and/or validates it (reject with a 400). Pipes run after guards, before the handler. The star is ValidationPipe, which works with class-validator decorators on DTO classes.

Built-in pipes

• ParseIntPipe, ParseFloatPipe, ParseBoolPipe — type coercion + validation
• ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe — format checks
• DefaultValuePipe — supply a default before another pipe runs
• ValidationPipe — the big one: validates DTOs with class-validator

export class CreateCatDto {
  @IsString() @IsNotEmpty()
  name: string;

  @IsInt() @Min(0) @Max(30)
  age: number;

  @IsOptional() @IsString()
  breed?: string;
}

// Globally (recommended — one line in main.ts):
app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));

// Or per controller/handler:
@UsePipes(new ValidationPipe({ whitelist: true }))
@Post() create(@Body() dto: CreateCatDto) { ... }

Key options

7. Guards, Auth & the Execution Context

Guards decide whether a request may proceed (auth, roles, rate limits…). They implement CanActivate and return a boolean — or throw an exception to deny. Guards run before interceptors and pipes.

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(ctx: ExecutionContext): boolean {
    const roles = this.reflector.get<string[]>('roles', ctx.getHandler()) ?? [];
    if (roles.length === 0) return true; // no @Roles() → public
    const req = ctx.switchToHttp().getRequest();
    return roles.includes(req.user?.role);
  }
}

// Usage:
@Roles('admin')                 // custom decorator: SetMetadata('roles', ['admin'])
@Post() create(@Body() dto: CreateCatDto) { ... }

How real apps do auth (JWT flow)

// In the module (recommended — works with DI):
providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }]
// or app-level (no DI):
app.useGlobalGuards(new JwtAuthGuard());

8. Interceptors, Exception Filters & Middleware

The remaining AOP (aspect-oriented) primitives wrap the request pipeline. Learning the order they run in is the key to reading any NestJS request path.

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const started = Date.now();
    return next.handle().pipe(
      map((data) => ({ data, ok: true })),   // wrap every response
      tap(() => console.log(`took ${Date.now() - started}ms`)),
    );
  }
}

@Catch(NotFoundException)
export class NotFoundFilter implements ExceptionFilter {
  catch(exception: NotFoundException, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse();
    res.status(404).json({ code: 'NOT_FOUND', message: exception.message });
  }
}

9. Integrations — Config, Databases & Swagger

NestJS ships first-party modules for the boring-but-essential infrastructure. These follow the same pattern: a forRoot (or forRootAsync) registration that produces a global provider.

Configuration — @nestjs/config

// app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true, envFilePath: ['.env', '.env.local'] }),
  ],
})
export class AppModule {}

// anywhere:
constructor(private readonly config: ConfigService) {}
const port = this.config.get<number>('PORT', 3000);

Database — TypeORM vs Prisma

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit {
  async onModuleInit() { await this.$connect(); }   // lifecycle hook
}

@Module({ providers: [PrismaService], exports: [PrismaService] })
export class PrismaModule {}

// cats.service.ts
constructor(private readonly prisma: PrismaService) {}
async findAll() { return this.prisma.cat.findMany(); }

More first-party modules you'll meet

10. Testing & Tooling

NestJS is designed for testability — DI means you override providers with mocks in one line. Jest comes preconfigured; the e2e harness boots the whole app with supertest.

describe('CatsController', () => {
  let controller: CatsController;

  beforeEach(async () => {
    const moduleRef = await Test.createTestingModule({
      controllers: [CatsController],
      providers: [{ provide: CatsService, useValue: { findAll: jest.fn().mockResolvedValue([]) } }],
    }).compile();

    controller = moduleRef.get(CatsController);
  });

  it('returns the mocked list', async () => {
    await expect(controller.findAll()).resolves.toEqual([]);
  });
});

// test/app.e2e-spec.ts
const app = await NestFactory.create(AppModule);
await app.init();
await request(app.getHttpServer())
  .get('/api/cats')
  .expect(200)
  .expect((res) => expect(res.body).toBeInstanceOf(Array));

Tooling notes

• Build speed: nest build --builder swc (or tsc for type-strict builds). SWC is dramatically faster; keep tsc --noEmit in CI for type checking.
• Editor: the Nest generator emits .vscode/launch.json debug configs; start:debug + Chrome DevTools is the standard flow.
• Monorepos: Nest apps work well in pnpm/nx monorepos; nest g app / nest g library exist for multi-app setups.
• Version pinning: check package.json — v10 vs v11 differ subtly in Node/TS requirements (v11 baseline: Node ≥ 20, TS ≥ 5.x).

11. NestJS vs Express vs Fastify

All three run on Node and are TypeScript-friendly, but they occupy very different points on the structure axis. NestJS is not a competitor to Express in the same tier — it's an opinionated layer on top of it (or Fastify).

12. When to Use NestJS — & Your First-Project Checklist

Jumping into an existing NestJS project — read in this order

13. References

• 1
  NestJS Official Documentation

  The authoritative reference — first steps, overview, and every technique chapter.
• 2
  nestjs/nest — GitHub

  Source code, releases, and roadmap. The framework is MIT-licensed and actively maintained.
• 3
  Nest CLI Overview

  All nest commands: new, generate schematics, build, start, and flags.
• 4
  Custom Providers

  useClass / useValue / useFactory / useExisting, injection tokens, and provider scopes.
• 5
  Pipes — Validation & Transformation

  Built-in pipes, ValidationPipe options, and custom pipe authoring.
• 6
  Guards & Execution Context

  CanActivate, the ExecutionContext abstraction, and binding guards.
• 7
  Interceptors & Exception Filters

  RxJS-based interceptors and centralized error handling with ArgumentsHost.
• 8
  Lifecycle Events

  OnModuleInit / OnApplicationShutdown etc. — where connect/disconnect logic lives.
• 9
  Prisma + NestJS Recipe

  The canonical PrismaService setup — pairs with the Prisma ORM study note in this collection.
• 10
  Authentication (JWT + Passport)

  The official JWT/Passport walkthrough — the base most production auth flows build on.
• 11
  @nestjs/core on npm

  Package page with version history, peer deps (Node/TS/Express), and weekly downloads.
• 12
  NestJS Releases / Changelog

  Primary source for major-version changes (v9 → v10 → v11) and deprecations.