🦅 Skill: nestjs-pro (v1.0.0)

Executive Summary

📋 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

• 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