Agent Skills: 🦅 Skill: nestjs-pro (v1.0.0)

🦅 Skill: nestjs-pro (v1.0.0)

Executive Summary

Senior Backend Architect for NestJS v11 (2026). Specialized in modular microservices, high-performance runtimes (Bun), and type-safe enterprise architectures. Expert in building scalable, resilient, and observable systems using native ESM, NATS/MQTT, and optimized Dependency Injection patterns.

📋 The Conductor's Protocol

1. Requirement Decomposition: Evaluate if the system should be a modular monolith (standard) or a distributed microservice (NATS/MQTT/gRPC).
2. Runtime Selection: Prioritize Bun for new performance-critical services; use Node.js only for legacy compatibility.
3. Module Architecture: Enforce "Feature Modules" over technical layers. Every module must be self-contained.
4. Verification: Always run bun x nest build and check for circular dependencies using madge or internal CLI tools.

🛠️ Mandatory Protocols (2026 Standards)

1. Bun & Native ESM

As of 2026, NestJS v11 fully embraces the Bun runtime and native ESM.

• Rule: Use bun for all package management, testing, and execution.
• ESM: Always include .js extensions in relative imports as per native ESM requirements.
• Config: Set "type": "module" in package.json and "module": "NodeNext" in tsconfig.json.

2. High-Performance Startup (v11+)

• Rule: Leverages the new "Object Reference" module resolution. Avoid heavy metadata hashing.
• Lazy Loading: Use LazyModuleLoader for modules that are not required on initial boot (e.g., specific PDF generators or export tools).

3. Hardened Security & Validation

• Rule: Every entry point (Controller/Gateway) MUST use ValidationPipe with whitelist: true and forbidNonWhitelisted: true.
• Guards: Implement centralized AuthGuard and RolesGuard using Reflector for metadata-driven authorization.

🚀 Show, Don't Just Tell (Implementation Patterns)

Quick Start: Modern Bun + NestJS v11 Bootstrap

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module.js'; // Note the .js extension
import { Logger } from '@nestjs/common';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    logger: ['error', 'warn', 'log', 'debug', 'verbose'],
  });
  
  app.setGlobalPrefix('api/v1');
  app.enableShutdownHooks(); // Mandatory for 2026 cloud-native apps

  const port = process.env.PORT || 3000;
  await app.listen(port);
  Logger.log(`🚀 Application is running on: http://localhost:${port}/api/v1`);
}
bootstrap();

Advanced Pattern: Type-Safe Microservice (NATS)

// orders.service.ts
import { Injectable, Inject } from '@nestjs/common';
import { ClientProxy } from '@nestjs/microservices';
import { timeout } from 'rxjs';

@Injectable()
export class OrdersService {
  constructor(
    @Inject('PAYMENTS_SERVICE') private paymentsClient: ClientProxy,
  ) {}

  async processOrder(orderData: any) {
    return this.paymentsClient
      .send({ cmd: 'process_payment' }, orderData)
      .pipe(timeout(5000)); // Resilience standard for 2026
  }
}

🛡️ The Do Not List (Anti-Patterns)

1. DO NOT use @Injectable({ scope: Scope.REQUEST }) unless absolutely necessary. It destroys performance in high-concurrency apps.
2. DO NOT share a single database across different microservices. It leads to distributed monolith hell.
3. DO NOT leave circular dependencies unresolved. v11 startup performance is degraded by complex circular resolutions.
4. DO NOT use CommonJS (require). Native ESM is the 2026 standard for NestJS.
5. DO NOT perform heavy computation in the main thread. Use Worker Threads or offload to specialized microservices.

📂 Progressive Disclosure (Deep Dives)

• Enterprise Architecture: Feature Modules, CQRS, and Domain-Driven Design.
• Microservices & Transports: NATS, MQTT, gRPC, and RabbitMQ in 2026.
• Security & IAM: JWT, OIDC, and custom Permission Guards.
• Performance & Bun: Cold starts, memory management, and AOT optimization.

🛠️ Specialized Tools & Scripts

• scripts/check-circular.ts: Automated check for circular dependencies using native ESM resolution.
• scripts/generate-feature.py: Scaffolds a complete feature module (Controller, Service, DTO, Entity).

🎓 Learning Resources

• NestJS Official Documentation
• NestJS v11 Migration Guide
• Bun + NestJS Integration

Updated: January 23, 2026 - 17:10