Skip to content

ever-co/ever-works / .agents/skills/nestjs-best-practices

nestjs-best-practices

Verified

NestJS best practices and architecture patterns for building production-ready applications. This skill should be used when writing, reviewing, or refactoring NestJS code to ensure proper patterns for modules, dependency injection, security, and performance.

FileKindSize
AGENTS.mdmarkdown154.2 KB
README.mdmarkdown4.7 KB
SKILL.mdskill md4.8 KB
rules/_sections.mdmarkdown2.1 KB
rules/_template.mdmarkdown633 B
rules/api-use-dto-serialization.mdmarkdown4.2 KB
rules/api-use-interceptors.mdmarkdown5.4 KB
rules/api-use-pipes.mdmarkdown5.3 KB
rules/api-versioning.mdmarkdown4.7 KB
rules/arch-avoid-circular-deps.mdmarkdown1.9 KB
rules/arch-feature-modules.mdmarkdown2.3 KB
rules/arch-module-sharing.mdmarkdown3.7 KB
rules/arch-single-responsibility.mdmarkdown2.8 KB
rules/arch-use-events.mdmarkdown2.9 KB
rules/arch-use-repository-pattern.mdmarkdown2.7 KB
rules/db-avoid-n-plus-one.mdmarkdown3.8 KB
rules/db-use-migrations.mdmarkdown3.7 KB
rules/db-use-transactions.mdmarkdown3.6 KB
rules/devops-graceful-shutdown.mdmarkdown5.5 KB
rules/devops-use-config-module.mdmarkdown4.2 KB
rules/devops-use-logging.mdmarkdown5.1 KB
rules/di-avoid-service-locator.mdmarkdown2.8 KB
rules/di-interface-segregation.mdmarkdown5.0 KB
rules/di-liskov-substitution.mdmarkdown6.8 KB
rules/di-prefer-constructor-injection.mdmarkdown2.2 KB
rules/di-scope-awareness.mdmarkdown2.5 KB
rules/di-use-interfaces-tokens.mdmarkdown2.5 KB
rules/error-handle-async-errors.mdmarkdown3.4 KB
rules/error-throw-http-exceptions.mdmarkdown3.0 KB
rules/error-use-exception-filters.mdmarkdown3.4 KB
rules/micro-use-health-checks.mdmarkdown6.1 KB
rules/micro-use-patterns.mdmarkdown5.0 KB
rules/micro-use-queues.mdmarkdown5.7 KB
rules/perf-async-hooks.mdmarkdown2.8 KB
rules/perf-lazy-loading.mdmarkdown3.6 KB
rules/perf-optimize-database.mdmarkdown3.0 KB
rules/perf-use-caching.mdmarkdown3.3 KB
rules/security-auth-jwt.mdmarkdown3.8 KB
rules/security-rate-limiting.mdmarkdown3.1 KB
rules/security-sanitize-output.mdmarkdown3.7 KB
rules/security-use-guards.mdmarkdown3.4 KB
rules/security-validate-all-input.mdmarkdown3.2 KB
rules/test-e2e-supertest.mdmarkdown4.4 KB
rules/test-mock-external-services.mdmarkdown4.2 KB
rules/test-use-testing-module.mdmarkdown4.1 KB
scripts/build-agents.tsscript8.1 KB
scripts/build.shscript369 B
scripts/package-lock.jsonmanifest7.7 KB
scripts/package.jsonmanifest410 B

rules/micro-use-health-checks.md

View on GitHub
---
title: Implement Health Checks for Microservices
impact: MEDIUM-HIGH
impactDescription: Health checks enable orchestrators to manage service lifecycle
tags: microservices, health-checks, terminus, kubernetes
---

## Implement Health Checks for Microservices

Implement liveness and readiness probes using `@nestjs/terminus`. Liveness checks determine if the service should be restarted. Readiness checks determine if the service can accept traffic. Proper health checks enable Kubernetes and load balancers to route traffic correctly.

**Incorrect (simple ping that doesn't check dependencies):**

```typescript
// Simple ping that doesn't check dependencies
@Controller('health')
export class HealthController {
	@Get()
	check(): string {
		return 'OK'; // Service might be unhealthy but returns OK
	}
}

// Health check that blocks on slow dependencies
@Controller('health')
export class HealthController {
	@Get()
	async check(): Promise<string> {
		// If database is slow, health check times out
		await this.userRepo.findOne({ where: { id: '1' } });
		await this.redis.ping();
		await this.externalApi.healthCheck();
		return 'OK';
	}
}
```

**Correct (use @nestjs/terminus for comprehensive health checks):**

```typescript
// Use @nestjs/terminus for comprehensive health checks
import {
  HealthCheckService,
  HttpHealthIndicator,
  TypeOrmHealthIndicator,
  HealthCheck,
  DiskHealthIndicator,
  MemoryHealthIndicator,
} from '@nestjs/terminus';

@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private http: HttpHealthIndicator,
    private db: TypeOrmHealthIndicator,
    private disk: DiskHealthIndicator,
    private memory: MemoryHealthIndicator,
  ) {}

  // Liveness probe - is the service alive?
  @Get('live')
  @HealthCheck()
  liveness() {
    return this.health.check([
      // Basic checks only
      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024), // 200MB
    ]);
  }

  // Readiness probe - can the service handle traffic?
  @Get('ready')
  @HealthCheck()
  readiness() {
    return this.health.check([
      () => this.db.pingCheck('database'),
      () =>
        this.http.pingCheck('redis', 'http://redis:6379', { timeout: 1000 }),
      () =>
        this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
    ]);
  }

  // Deep health check for debugging
  @Get('deep')
  @HealthCheck()
  deepCheck() {
    return this.health.check([
      () => this.db.pingCheck('database'),
      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024),
      () => this.memory.checkRSS('memory_rss', 300 * 1024 * 1024),
      () =>
        this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
      () =>
        this.http.pingCheck('external-api', 'https://api.example.com/health'),
    ]);
  }
}

// Custom indicator for business-specific health
@Injectable()
export class QueueHealthIndicator extends HealthIndicator {
  constructor(private queueService: QueueService) {
    super();
  }

  async isHealthy(key: string): Promise<HealthIndicatorResult> {
    const queueStats = await this.queueService.getStats();

    const isHealthy = queueStats.failedCount < 100;
    const result = this.getStatus(key, isHealthy, {
      waiting: queueStats.waitingCount,
      active: queueStats.activeCount,
      failed: queueStats.failedCount,
    });

    if (!isHealthy) {
      throw new HealthCheckError('Queue unhealthy', result);
    }

    return result;
  }
}

// Redis health indicator
@Injectable()
export class RedisHealthIndicator extends HealthIndicator {
  constructor(@InjectRedis() private redis: Redis) {
    super();
  }

  async isHealthy(key: string): Promise<HealthIndicatorResult> {
    try {
      const pong = await this.redis.ping();
      return this.getStatus(key, pong === 'PONG');
    } catch (error) {
      throw new HealthCheckError('Redis check failed', this.getStatus(key, false));
    }
  }
}

// Use custom indicators
@Get('ready')
@HealthCheck()
readiness() {
  return this.health.check([
    () => this.db.pingCheck('database'),
    () => this.redis.isHealthy('redis'),
    () => this.queue.isHealthy('job-queue'),
  ]);
}

// Graceful shutdown handling
@Injectable()
export class GracefulShutdownService implements OnApplicationShutdown {
  private isShuttingDown = false;

  isShutdown(): boolean {
    return this.isShuttingDown;
  }

  async onApplicationShutdown(signal: string): Promise<void> {
    this.isShuttingDown = true;
    console.log(`Shutting down on ${signal}`);

    // Wait for in-flight requests
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

// Health check respects shutdown state
@Get('ready')
@HealthCheck()
readiness() {
  if (this.shutdownService.isShutdown()) {
    throw new ServiceUnavailableException('Shutting down');
  }

  return this.health.check([
    () => this.db.pingCheck('database'),
  ]);
}
```

### Kubernetes Configuration

```yaml
# Kubernetes deployment with probes
apiVersion: apps/v1
kind: Deployment
metadata:
    name: api-service
spec:
    template:
        spec:
            containers:
                - name: api
                  image: api-service:latest
                  ports:
                      - containerPort: 3000
                  livenessProbe:
                      httpGet:
                          path: /health/live
                          port: 3000
                      initialDelaySeconds: 30
                      periodSeconds: 10
                      timeoutSeconds: 5
                      failureThreshold: 3
                  readinessProbe:
                      httpGet:
                          path: /health/ready
                          port: 3000
                      initialDelaySeconds: 5
                      periodSeconds: 5
                      timeoutSeconds: 3
                      failureThreshold: 3
                  startupProbe:
                      httpGet:
                          path: /health/live
                          port: 3000
                      initialDelaySeconds: 0
                      periodSeconds: 5
                      failureThreshold: 30
```

Reference: [NestJS Terminus](https://docs.nestjs.com/recipes/terminus)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall