NestJS

---

name: NestJS description: Avoid common NestJS mistakes — DI scoping, circular dependencies, validation pipes, and module organization traps. metadata: {"clawdbot":{"emoji":"🐱","requires":{"bins":["node"]},"os":["linux","darwin","win32"]}}

---

Dependency Injection

Provider not available — must be in providers array AND exports if used by other modules

Circular dependency crashes — use forwardRef(() => Module) in both modules

Default scope is singleton — same instance across requests, careful with state

Request-scoped provider — @Injectable({ scope: Scope.REQUEST }), propagates to dependents

Module Organization

Import module, not provider directly — imports: [UserModule] not providers: [UserService]

exports makes providers available to importers — without it, provider stays private

Global modules need @Global() decorator — only for truly shared (config, logger)

forRoot() vs forRootAsync() — async for when config depends on other providers

Validation

ValidationPipe needs class-validator decorators — plain classes won't validate

Enable transform: true for auto-transformation — string "1" to number 1

whitelist: true strips unknown properties — forbidNonWhitelisted: true to error instead

Nested objects need @ValidateNested() AND @Type(() => NestedDto) — both required

Execution Order

Middleware → Guards → Interceptors (pre) → Pipes → Handler → Interceptors (post) → Filters

Guards can't access transformed body — run before pipes

Global pipes run before route pipes — but after guards

Exception filters catch errors from entire chain — including guards and pipes

Exception Handling

throw new HttpException() not return — must throw for filter to catch

Custom exceptions extend HttpException — or implement ExceptionFilter

Unhandled exceptions become 500 — wrap external calls in try/catch

Built-in exceptions: BadRequestException, NotFoundException, etc. — use these, not generic HttpException

Testing

createTestingModule doesn't auto-mock — provide mocks explicitly in providers

Override with .overrideProvider(X).useValue(mock) — before .compile()

E2E tests need app.init() — and app.close() in afterAll

Request-scoped providers complicate unit tests — consider making them singleton when possible

Common Mistakes

@Body() without DTO returns plain object — no validation, no transformation

@Param('id') is always string — use ParseIntPipe for number: @Param('id', ParseIntPipe)

Guards returning false gives 403 — throw specific exception for better error messages

Async providers need factory — useFactory: async () => await createConnection()

Forgetting await on async service methods — returns Promise, not value

ValidationPipe needs class-validator decorators — plain classes won't validate

Enable transform: true for auto-transformation — string "1" to number 1

whitelist: true strips unknown properties — forbidNonWhitelisted: true to error instead

Nested objects need @ValidateNested() AND @Type(() => NestedDto) — both required