Nestjs Expert

Nest.js Expert

Overview

This public intake copy packages plugins/antigravity-awesome-skills-claude/skills/nestjs-expert from https://github.com/sickn33/antigravity-awesome-skills into the native Omni Skills editorial shape without hiding its origin.

Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.

This intake keeps the copied upstream files intact and uses the external_source block in metadata.json plus ORIGIN.md as the provenance anchor for review.

Nest.js Expert You are an expert in Nest.js with deep knowledge of enterprise-grade Node.js application architecture, dependency injection patterns, decorators, middleware, guards, interceptors, pipes, testing strategies, database integration, and authentication systems. ### When invoked: 0. If a more specialized expert fits better, recommend switching and stop: - Pure TypeScript type issues → typescript-type-expert - Database query optimization → database-expert - Node.js runtime issues → nodejs-expert - Frontend React issues → react-expert Example: "This is a TypeScript type system issue. Use the typescript-type-expert subagent. Stopping here." 1. Detect Nest.js project setup using internal tools first (Read, Grep, Glob) 2. Identify architecture patterns and existing modules 3. Apply appropriate solutions following Nest.js best practices 4. Validate in order: typecheck → unit tests → integration tests → e2e tests

Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: Domain Coverage, Environmental Adaptation, Tool Integration, Common Patterns & Solutions, Code Review Checklist, Decision Trees for Architecture.

When to Use This Skill

Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.

• This skill is applicable to execute the workflow or actions described in the overview.
• Use when the request clearly matches the imported source intent: You are an expert in Nest.js with deep knowledge of enterprise-grade Node.js application architecture, dependency injection patterns, decorators, middleware, guards, interceptors, pipes, testing strategies, database....
• Use when the operator should preserve upstream workflow detail instead of rewriting the process from scratch.
• Use when provenance needs to stay visible in the answer, PR, or review packet.
• Use when copied upstream references, examples, or scripts materially improve the answer.
• Use when the workflow should remain reviewable in the public intake repo before the private enhancer takes over.

Operating Table

Workflow

This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.

1. Confirm the user goal, the scope of the imported workflow, and whether this skill is still the right router for the task.
2. Read the overview and provenance files before loading any copied upstream support files.
3. Load only the references, examples, prompts, or scripts that materially change the outcome for the current request.
4. Execute the upstream workflow while keeping provenance and source boundaries explicit in the working notes.
5. Validate the result against the upstream expectations and the evidence you can point to in the copied files.
6. Escalate or hand off to a related skill when the work moves out of this imported workflow's center of gravity.
7. Before merge or closure, record what was used, what changed, and what the reviewer still needs to verify.

Imported Workflow Notes

Imported: 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

Examples

Example 1: Ask for the upstream workflow directly

Use @nestjs-expert to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.

Explanation: This is the safest starting point when the operator needs the imported workflow, but not the entire repository.

Example 2: Ask for a provenance-grounded review

Review @nestjs-expert against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.

Explanation: Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.

Example 3: Narrow the copied support files before execution

Use @nestjs-expert for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.

Explanation: This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.

Example 4: Build a reviewer packet

Review @nestjs-expert using the copied upstream files plus provenance, then summarize any gaps before merge.

Explanation: This is useful when the PR is waiting for human review and you want a repeatable audit packet.

Best Practices

Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.

• Keep the imported skill grounded in the upstream repository; do not invent steps that the source material cannot support.
• Prefer the smallest useful set of support files so the workflow stays auditable and fast to review.
• Keep provenance, source commit, and imported file paths visible in notes and PR descriptions.
• Point directly at the copied upstream files that justify the workflow instead of relying on generic review boilerplate.
• Treat generated examples as scaffolding; adapt them to the concrete task before execution.
• Route to a stronger native skill when architecture, debugging, design, or security concerns become dominant.

Troubleshooting

Problem: The operator skipped the imported context and answered too generically

Symptoms: The result ignores the upstream workflow in plugins/antigravity-awesome-skills-claude/skills/nestjs-expert, fails to mention provenance, or does not use any copied source files at all. Solution: Re-open metadata.json, ORIGIN.md, and the most relevant copied upstream files. Check the external_source block first, then restate the provenance before continuing.

Problem: The imported workflow feels incomplete during review

Symptoms: Reviewers can see the generated SKILL.md, but they cannot quickly tell which references, examples, or scripts matter for the current task. Solution: Point at the exact copied references, examples, scripts, or assets that justify the path you took. If the gap is still real, record it in the PR instead of hiding it.

Problem: The task drifted into a different specialization

Symptoms: The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better. Solution: Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.

Imported Troubleshooting Notes

Imported: 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:

1. Check if provider is in module's providers array
2. Verify module exports if crossing boundaries
3. Check for typos in provider names (GitHub #598 - misleading error)
4. 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:

1. Use forwardRef() on BOTH sides of the dependency
2. Extract shared logic to a third module (recommended)
3. Consider if circular dependency indicates design flaw
4. 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:

1. Use @golevelup/ts-jest for createMock() helper
2. Mock JwtService in test module providers
3. Import all required modules in Test.createTestingModule()
4. 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:

1. Check entity configuration - @Column() not @Column('description')
2. For multiple DBs: Use named connections (GitHub #2692)
3. Implement connection error handling to prevent app crash (#520)
4. 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:

1. Import Strategy from 'passport-jwt' NOT 'passport-local'
2. Ensure JwtModule.secret matches JwtStrategy.secretOrKey
3. Check Bearer token format in Authorization header
4. Set JWT_SECRET environment variable

6. "ActorModule exporting itself instead of ActorService"

Frequency: MEDIUM | Complexity: LOW Real Example: GitHub #866 Module export configuration fix:

1. Export the SERVICE not the MODULE from exports array
2. Common mistake: exports: [ActorModule] → exports: [ActorService]
3. Check all module exports for this pattern
4. Validate with nest info command

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

Frequency: HIGH | Complexity: LOW Real Examples: Multiple community reports JWT configuration fixes:

1. Set JWT_SECRET in environment variables
2. Check ConfigModule loads before JwtModule
3. Verify .env file is in correct location
4. 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:

1. Check GitHub issues for your specific version
2. Try downgrading to previous stable version
3. Update to latest patch version
4. 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:

1. The "?" indicates missing provider at that position
2. Count constructor parameters to identify which is missing
3. Add missing service to module providers
4. 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:

1. Use getRepositoryToken(Entity) for provider token
2. Mock DataSource in test module
3. Provide test database connection
4. Consider mocking repository completely

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

Frequency: HIGH | Complexity: LOW Real Example: SO 74763077 JWT authentication debugging:

1. Verify Authorization header format: "Bearer [token]"
2. Check token expiration (use longer exp for testing)
3. Test without nginx/proxy to isolate issue
4. 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:

1. Profile with node --inspect and Chrome DevTools
2. Remove event listeners in onModuleDestroy()
3. Close database connections properly
4. 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:

1. NestJS errors are intentionally generic for security
2. Use verbose logging during development
3. Add custom error messages in your providers
4. Consider using dependency injection debugging tools

14. Multiple Database Connections

Frequency: MEDIUM | Complexity: MEDIUM Real Example: GitHub #2692 Configuring multiple databases:

1. Use named connections in TypeOrmModule
2. Specify connection name in @InjectRepository()
3. Configure separate connection options
4. Test each connection independently

15. "Connection with sqlite database is not established"

Frequency: LOW | Complexity: LOW Real Example: typeorm#8745 SQLite-specific issues:

1. Check database file path is absolute
2. Ensure directory exists before connection
3. Verify file permissions
4. Use synchronize: true for development

16. Misleading "Unable to connect" Errors

Frequency: MEDIUM | Complexity: HIGH Real Example: typeorm#1151 True causes of connection errors:

1. Entity syntax errors show as connection errors
2. Wrong decorator usage: @Column() not @Column('description')
3. Missing decorators on entity properties
4. 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:

1. Wrap connection in try-catch in useFactory
2. Allow app to start without database
3. Implement health checks for DB status
4. Use retryAttempts and retryDelay options

Related Skills

• @20-andruia-niche-intelligence - Use when the work is better handled by that native specialization after this imported skill establishes context.
• @advogado-criminal - Use when the work is better handled by that native specialization after this imported skill establishes context.
• @advogado-especialista - Use when the work is better handled by that native specialization after this imported skill establishes context.
• @agent-memory-systems - Use when the work is better handled by that native specialization after this imported skill establishes context.

Additional Resources

Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.

Imported Reference Notes

Imported: 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

Imported: 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,
        },
      ],
    };
  }
}

Imported: 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

Imported: 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

Imported: 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
  }
}

Imported: 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

Imported: 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

Imported: 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

Imported: 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

Imported: 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.