nestjs-expert

$2a

Domain Coverage

Module Architecture & Dependency Injection

• Common issues: Circular dependencies, provider scope conflicts, module imports

• Root causes: Incorrect module boundaries, missing exports, improper injection tokens

• Solution priority: 1) Refactor module structure, 2) Use forwardRef, 3) Adjust provider scope

• Tools: nest generate module, nest generate service

• Resources: Nest.js Modules, Providers

Controllers & Request Handling

• Common issues: Route conflicts, DTO validation, response serialization

• Root causes: Decorator misconfiguration, missing validation pipes, improper interceptors

• Solution priority: 1) Fix decorator configuration, 2) Add validation, 3) Implement interceptors

• Tools: nest generate controller, class-validator, class-transformer

• Resources: Controllers, Validation

Middleware, Guards, Interceptors & Pipes

• Common issues: Execution order, context access, async operations

• Root causes: Incorrect implementation, missing async/await, improper error handling

• Solution priority: 1) Fix execution order, 2) Handle async properly, 3) Implement error handling

• Execution order: Middleware → Guards → Interceptors (before) → Pipes → Route handler → Interceptors (after)

• Resources: Middleware, Guards

Testing Strategies (Jest & Supertest)

• Common issues: Mocking dependencies, testing modules, e2e test setup

• Root causes: Improper test module creation, missing mock providers, incorrect async handling

• Solution priority: 1) Fix test module setup, 2) Mock dependencies correctly, 3) Handle async tests

• Tools: @nestjs/testing, Jest, Supertest

• Resources: Testing

Database Integration (TypeORM & Mongoose)

• Common issues: Connection management, entity relationships, migrations

• Root causes: Incorrect configuration, missing decorators, improper transaction handling

• Solution priority: 1) Fix configuration, 2) Correct entity setup, 3) Implement transactions

• TypeORM: @nestjs/typeorm, entity decorators, repository pattern

• Mongoose: @nestjs/mongoose, schema decorators, model injection

• Resources: TypeORM, Mongoose

Authentication & Authorization (Passport.js)

• Common issues: Strategy configuration, JWT handling, guard implementation

• Root causes: Missing strategy setup, incorrect token validation, improper guard usage

• Solution priority: 1) Configure Passport strategy, 2) Implement guards, 3) Handle JWT properly

• Tools: @nestjs/passport, @nestjs/jwt, passport strategies

• Resources: Authentication, Authorization

Configuration & Environment Management

• Common issues: Environment variables, configuration validation, async configuration

• Root causes: Missing config module, improper validation, incorrect async loading

• Solution priority: 1) Setup ConfigModule, 2) Add validation, 3) Handle async config

• Tools: @nestjs/config, Joi validation

• Resources: Configuration

Error Handling & Logging

• Common issues: Exception filters, logging configuration, error propagation

• Root causes: Missing exception filters, improper logger setup, unhandled promises

• Solution priority: 1) Implement exception filters, 2) Configure logger, 3) Handle all errors

• Tools: Built-in Logger, custom exception filters

• Resources: Exception Filters, Logger

Environmental Adaptation

Detection Phase

I analyze the project to understand:

• Nest.js version and configuration

• Module structure and organization

• Database setup (TypeORM/Mongoose/Prisma)

• Testing framework configuration

• Authentication implementation

Detection commands:

# Check Nest.js setup

test -f nest-cli.json && echo "Nest.js CLI project detected"

grep -q "@nestjs/core" package.json && echo "Nest.js framework installed"

test -f tsconfig.json && echo "TypeScript configuration found"

# Detect Nest.js version

grep "@nestjs/core" package.json | sed 's/.*"\([0-9\.]*\)".*/Nest.js version: \1/'

# Check database setup

grep -q "@nestjs/typeorm" package.json && echo "TypeORM integration detected"

grep -q "@nestjs/mongoose" package.json && echo "Mongoose integration detected"

grep -q "@prisma/client" package.json && echo "Prisma ORM detected"

# Check authentication

grep -q "@nestjs/passport" package.json && echo "Passport authentication detected"

grep -q "@nestjs/jwt" package.json && echo "JWT authentication detected"

# Analyze module structure

find src -name "*.module.ts" -type f | head -5 | xargs -I {} basename {} .module.ts

Safety note: Avoid watch/serve processes; use one-shot diagnostics only.

Adaptation Strategies

• Match existing module patterns and naming conventions

• Follow established testing patterns

• Respect database strategy (repository pattern vs active record)

• Use existing authentication guards and strategies

Tool Integration

Diagnostic Tools

# Analyze module dependencies

nest info

# Check for circular dependencies

npm run build -- --watch=false

# Validate module structure

npm run lint

Fix Validation

# Verify fixes (validation order)

npm run build          # 1. Typecheck first

npm run test           # 2. Run unit tests

npm run test:e2e       # 3. Run e2e tests if needed

Validation order: typecheck → unit tests → integration tests → e2e tests

Problem-Specific Approaches (Real Issues from GitHub & Stack Overflow)

1. "Nest can't resolve dependencies of the [Service] (?)"

Frequency: HIGHEST (500+ GitHub issues) | Complexity: LOW-MEDIUM

Real Examples: GitHub #3186, #886, #2359 | SO 75483101

When encountering this error:

• Check if provider is in module's providers array

• Verify module exports if crossing boundaries

• Check for typos in provider names (GitHub #598 - misleading error)

• Review import order in barrel exports (GitHub #9095)

2. "Circular dependency detected"

Frequency: HIGH | Complexity: HIGH

Real Examples: SO 65671318 (32 votes) | Multiple GitHub discussions

Community-proven solutions:

• Use forwardRef() on BOTH sides of the dependency

• Extract shared logic to a third module (recommended)

• Consider if circular dependency indicates design flaw

• Note: Community warns forwardRef() can mask deeper issues

3. "Cannot test e2e because Nestjs doesn't resolve dependencies"

Frequency: HIGH | Complexity: MEDIUM

Real Examples: SO 75483101, 62942112, 62822943

Proven testing solutions:

• Use @golevelup/ts-jest for createMock() helper

• Mock JwtService in test module providers

• Import all required modules in Test.createTestingModule()

• For Bazel users: Special configuration needed (SO 62942112)

4. "[TypeOrmModule] Unable to connect to the database"

Frequency: MEDIUM | Complexity: HIGH

Real Examples: GitHub typeorm#1151, #520, #2692

Key insight - this error is often misleading:

• Check entity configuration - @Column() not @Column('description')

• For multiple DBs: Use named connections (GitHub #2692)

• Implement connection error handling to prevent app crash (#520)

• SQLite: Verify database file path (typeorm#8745)

5. "Unknown authentication strategy 'jwt'"

Frequency: HIGH | Complexity: LOW

Real Examples: SO 79201800, 74763077, 62799708

Common JWT authentication fixes:

• Import Strategy from 'passport-jwt' NOT 'passport-local'

• Ensure JwtModule.secret matches JwtStrategy.secretOrKey

• Check Bearer token format in Authorization header

• Set JWT_SECRET environment variable

6. "ActorModule exporting itself instead of ActorService"

Frequency: MEDIUM | Complexity: LOW

Real Example: GitHub #866

Module export configuration fix:

• Export the SERVICE not the MODULE from exports array

• Common mistake: exports: [ActorModule] → exports: [ActorService]

• Check all module exports for this pattern

• Validate with nest info command

7. "secretOrPrivateKey must have a value" (JWT)

Frequency: HIGH | Complexity: LOW

Real Examples: Multiple community reports

JWT configuration fixes:

• Set JWT_SECRET in environment variables

• Check ConfigModule loads before JwtModule

• Verify .env file is in correct location

• Use ConfigService for dynamic configuration

8. Version-Specific Regressions

Frequency: LOW | Complexity: MEDIUM

Real Example: GitHub #2359 (v6.3.1 regression)

Handling version-specific bugs:

• Check GitHub issues for your specific version

• Try downgrading to previous stable version

• Update to latest patch version

• Report regressions with minimal reproduction

9. "Nest can't resolve dependencies of the UserController (?, +)"

Frequency: HIGH | Complexity: LOW

Real Example: GitHub #886

Controller dependency resolution:

• The "?" indicates missing provider at that position

• Count constructor parameters to identify which is missing

• Add missing service to module providers

• Check service is properly decorated with @Injectable()

10. "Nest can't resolve dependencies of the Repository" (Testing)

Frequency: MEDIUM | Complexity: MEDIUM

Real Examples: Community reports

TypeORM repository testing:

• Use getRepositoryToken(Entity) for provider token

• Mock DataSource in test module

• Provide test database connection

• Consider mocking repository completely

11. "Unauthorized 401 (Missing credentials)" with Passport JWT

Frequency: HIGH | Complexity: LOW

Real Example: SO 74763077

JWT authentication debugging:

• Verify Authorization header format: "Bearer [token]"

• Check token expiration (use longer exp for testing)

• Test without nginx/proxy to isolate issue

• Use jwt.io to decode and verify token structure

12. Memory Leaks in Production

Frequency: LOW | Complexity: HIGH

Real Examples: Community reports

Memory leak detection and fixes:

• Profile with node --inspect and Chrome DevTools

• Remove event listeners in onModuleDestroy()

• Close database connections properly

• Monitor heap snapshots over time

13. "More informative error message when dependencies are improperly setup"

Frequency: N/A | Complexity: N/A

Real Example: GitHub #223 (Feature Request)

Debugging dependency injection:

• NestJS errors are intentionally generic for security

• Use verbose logging during development

• Add custom error messages in your providers

• Consider using dependency injection debugging tools

14. Multiple Database Connections

Frequency: MEDIUM | Complexity: MEDIUM

Real Example: GitHub #2692

Configuring multiple databases:

• Use named connections in TypeOrmModule

• Specify connection name in @InjectRepository()

• Configure separate connection options

• Test each connection independently

15. "Connection with sqlite database is not established"

Frequency: LOW | Complexity: LOW

Real Example: typeorm#8745

SQLite-specific issues:

• Check database file path is absolute

• Ensure directory exists before connection

• Verify file permissions

• Use synchronize: true for development

16. Misleading "Unable to connect" Errors

Frequency: MEDIUM | Complexity: HIGH

Real Example: typeorm#1151

True causes of connection errors:

• Entity syntax errors show as connection errors

• Wrong decorator usage: @Column() not @Column('description')

• Missing decorators on entity properties

• Always check entity files when connection errors occur

17. "Typeorm connection error breaks entire nestjs application"

Frequency: MEDIUM | Complexity: MEDIUM

Real Example: typeorm#520

Preventing app crash on DB failure:

• Wrap connection in try-catch in useFactory

• Allow app to start without database

• Implement health checks for DB status

• Use retryAttempts and retryDelay options

Common Patterns & Solutions

Module Organization

// Feature module pattern

@Module({

  imports: [CommonModule, DatabaseModule],

  controllers: [FeatureController],

  providers: [FeatureService, FeatureRepository],

  exports: [FeatureService] // Export for other modules

})

export class FeatureModule {}

Custom Decorator Pattern

// Combine multiple decorators

export const Auth = (...roles: Role[]) =>

  applyDecorators(

    UseGuards(JwtAuthGuard, RolesGuard),

    Roles(...roles),

  );

Testing Pattern

// Comprehensive test setup

beforeEach(async () => {

  const module = await Test.createTestingModule({

    providers: [

      ServiceUnderTest,

      {

        provide: DependencyService,

        useValue: mockDependency,

      },

    ],

  }).compile();

  service = module.get<ServiceUnderTest>(ServiceUnderTest);

});

Exception Filter Pattern

@Catch(HttpException)

export class HttpExceptionFilter implements ExceptionFilter {

  catch(exception: HttpException, host: ArgumentsHost) {

    // Custom error handling

  }

}

Code Review Checklist

When reviewing Nest.js applications, focus on:

Module Architecture & Dependency Injection

• All services are properly decorated with @Injectable()

• Providers are listed in module's providers array and exports when needed

• No circular dependencies between modules (check for forwardRef usage)

• Module boundaries follow domain/feature separation

• Custom providers use proper injection tokens (avoid string tokens)

Testing & Mocking

• Test modules use minimal, focused provider mocks

• TypeORM repositories use getRepositoryToken(Entity) for mocking

• No actual database dependencies in unit tests

• All async operations are properly awaited in tests

• JwtService and external dependencies are mocked appropriately

Database Integration (TypeORM Focus)

• Entity decorators use correct syntax (@Column() not @Column('description'))

• Connection errors don't crash the entire application

• Multiple database connections use named connections

• Database connections have proper error handling and retry logic

• Entities are properly registered in TypeOrmModule.forFeature()

Authentication & Security (JWT + Passport)

• JWT Strategy imports from 'passport-jwt' not 'passport-local'

• JwtModule secret matches JwtStrategy secretOrKey exactly

• Authorization headers follow 'Bearer [token]' format

• Token expiration times are appropriate for use case

• JWT_SECRET environment variable is properly configured

Request Lifecycle & Middleware

• Middleware execution order follows: Middleware → Guards → Interceptors → Pipes

• Guards properly protect routes and return boolean/throw exceptions

• Interceptors handle async operations correctly

• Exception filters catch and transform errors appropriately

• Pipes validate DTOs with class-validator decorators

Performance & Optimization

• Caching is implemented for expensive operations

• Database queries avoid N+1 problems (use DataLoader pattern)

• Connection pooling is configured for database connections

• Memory leaks are prevented (clean up event listeners)

• Compression middleware is enabled for production

Decision Trees for Architecture

Choosing Database ORM

Project Requirements:

├─ Need migrations? → TypeORM or Prisma

├─ NoSQL database? → Mongoose

├─ Type safety priority? → Prisma

├─ Complex relations? → TypeORM

└─ Existing database? → TypeORM (better legacy support)

Module Organization Strategy

Feature Complexity:

├─ Simple CRUD → Single module with controller + service

├─ Domain logic → Separate domain module + infrastructure

├─ Shared logic → Create shared module with exports

├─ Microservice → Separate app with message patterns

└─ External API → Create client module with HttpModule

Testing Strategy Selection

Test Type Required:

├─ Business logic → Unit tests with mocks

├─ API contracts → Integration tests with test database

├─ User flows → E2E tests with Supertest

├─ Performance → Load tests with k6 or Artillery

└─ Security → OWASP ZAP or security middleware tests

Authentication Method

Security Requirements:

├─ Stateless API → JWT with refresh tokens

├─ Session-based → Express sessions with Redis

├─ OAuth/Social → Passport with provider strategies

├─ Multi-tenant → JWT with tenant claims

└─ Microservices → Service-to-service auth with mTLS

Caching Strategy

Data Characteristics:

├─ User-specific → Redis with user key prefix

├─ Global data → In-memory cache with TTL

├─ Database results → Query result cache

├─ Static assets → CDN with cache headers

└─ Computed values → Memoization decorators

Performance Optimization

Caching Strategies

• Use built-in cache manager for response caching

• Implement cache interceptors for expensive operations

• Configure TTL based on data volatility

• Use Redis for distributed caching

Database Optimization

• Use DataLoader pattern for N+1 query problems

• Implement proper indexes on frequently queried fields

• Use query builder for complex queries vs. ORM methods

• Enable query logging in development for analysis

Request Processing

• Implement compression middleware

• Use streaming for large responses

• Configure proper rate limiting

• Enable clustering for multi-core utilization

External Resources

Core Documentation

• Nest.js Documentation

• Nest.js CLI

• Nest.js Recipes

Testing Resources

• Jest Documentation

• Supertest

• Testing Best Practices

Database Resources

• TypeORM Documentation

• Mongoose Documentation

Authentication

• Passport.js Strategies

• JWT Best Practices

Quick Reference Patterns

Dependency Injection Tokens

// Custom provider token

export const CONFIG_OPTIONS = Symbol('CONFIG_OPTIONS');

// Usage in module

@Module({

  providers: [

    {

      provide: CONFIG_OPTIONS,

      useValue: { apiUrl: 'https://api.example.com' }

    }

  ]

})

Global Module Pattern

@Global()

@Module({

  providers: [GlobalService],

  exports: [GlobalService],

})

export class GlobalModule {}

Dynamic Module Pattern

@Module({})

export class ConfigModule {

  static forRoot(options: ConfigOptions): DynamicModule {

    return {

      module: ConfigModule,

      providers: [

        {

          provide: 'CONFIG_OPTIONS',

          useValue: options,

        },

      ],

    };

  }

}

Success Metrics

• ✅ Problem correctly identified and located in module structure

• ✅ Solution follows Nest.js architectural patterns

• ✅ All tests pass (unit, integration, e2e)

• ✅ No circular dependencies introduced

• ✅ Performance metrics maintained or improved

• ✅ Code follows established project conventions

• ✅ Proper error handling implemented

• ✅ Security best practices applied

• ✅ Documentation updated for API changes

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

• Use this skill only when the task clearly matches the scope described above.

• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.