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/devops-graceful-shutdown.md

View on GitHub
---
title: Implement Graceful Shutdown
impact: MEDIUM-HIGH
impactDescription: Proper shutdown handling ensures zero-downtime deployments
tags: devops, graceful-shutdown, lifecycle, kubernetes
---

## Implement Graceful Shutdown

Handle SIGTERM and SIGINT signals to gracefully shutdown your NestJS application. Stop accepting new requests, wait for in-flight requests to complete, close database connections, and clean up resources. This prevents data loss and connection errors during deployments.

**Incorrect (ignoring shutdown signals):**

```typescript
// Ignore shutdown signals
async function bootstrap() {
	const app = await NestFactory.create(AppModule);
	await app.listen(3000);
	// App crashes immediately on SIGTERM
	// In-flight requests fail
	// Database connections are abruptly closed
}

// Long-running tasks without cancellation
@Injectable()
export class ProcessingService {
	async processLargeFile(file: File): Promise<void> {
		// No way to interrupt this during shutdown
		for (let i = 0; i < file.chunks.length; i++) {
			await this.processChunk(file.chunks[i]);
			// May run for minutes, blocking shutdown
		}
	}
}
```

**Correct (enable shutdown hooks and handle cleanup):**

```typescript
// Enable shutdown hooks in main.ts
async function bootstrap() {
	const app = await NestFactory.create(AppModule);

	// Enable shutdown hooks
	app.enableShutdownHooks();

	// Optional: Add timeout for forced shutdown
	const server = await app.listen(3000);
	server.setTimeout(30000); // 30 second timeout

	// Handle graceful shutdown
	const signals = ['SIGTERM', 'SIGINT'];
	signals.forEach((signal) => {
		process.on(signal, async () => {
			console.log(`Received ${signal}, starting graceful shutdown...`);

			// Stop accepting new connections
			server.close(async () => {
				console.log('HTTP server closed');
				await app.close();
				process.exit(0);
			});

			// Force exit after timeout
			setTimeout(() => {
				console.error('Forced shutdown after timeout');
				process.exit(1);
			}, 30000);
		});
	});
}

// Lifecycle hooks for cleanup
@Injectable()
export class DatabaseService implements OnApplicationShutdown {
	private readonly connections: Connection[] = [];

	async onApplicationShutdown(signal?: string): Promise<void> {
		console.log(`Database service shutting down on ${signal}`);

		// Close all connections gracefully
		await Promise.all(this.connections.map((conn) => conn.close()));

		console.log('All database connections closed');
	}
}

// Queue processor with graceful shutdown
@Injectable()
export class QueueService implements OnApplicationShutdown, OnModuleDestroy {
	private isShuttingDown = false;

	onModuleDestroy(): void {
		this.isShuttingDown = true;
	}

	async onApplicationShutdown(): Promise<void> {
		// Wait for current jobs to complete
		await this.queue.close();
	}

	async processJob(job: Job): Promise<void> {
		if (this.isShuttingDown) {
			throw new Error('Service is shutting down');
		}
		await this.doWork(job);
	}
}

// WebSocket gateway cleanup
@WebSocketGateway()
export class EventsGateway implements OnApplicationShutdown {
	@WebSocketServer()
	server: Server;

	async onApplicationShutdown(): Promise<void> {
		// Notify all connected clients
		this.server.emit('shutdown', { message: 'Server is shutting down' });

		// Close all connections
		this.server.disconnectSockets();
	}
}

// Health check integration
@Injectable()
export class ShutdownService {
	private isShuttingDown = false;

	startShutdown(): void {
		this.isShuttingDown = true;
	}

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

@Controller('health')
export class HealthController {
	constructor(private shutdownService: ShutdownService) {}

	@Get('ready')
	@HealthCheck()
	readiness(): Promise<HealthCheckResult> {
		// Return 503 during shutdown - k8s stops sending traffic
		if (this.shutdownService.isShutdown()) {
			throw new ServiceUnavailableException('Shutting down');
		}

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

// Integrate with shutdown
@Injectable()
export class AppShutdownService implements OnApplicationShutdown {
	constructor(private shutdownService: ShutdownService) {}

	async onApplicationShutdown(): Promise<void> {
		// Mark as unhealthy first
		this.shutdownService.startShutdown();

		// Wait for k8s to update endpoints
		await this.sleep(5000);

		// Then proceed with cleanup
	}
}

// Request tracking for in-flight requests
@Injectable()
export class RequestTracker implements NestMiddleware, OnApplicationShutdown {
	private activeRequests = 0;
	private isShuttingDown = false;
	private shutdownPromise: Promise<void> | null = null;
	private resolveShutdown: (() => void) | null = null;

	use(req: Request, res: Response, next: NextFunction): void {
		if (this.isShuttingDown) {
			res.status(503).send('Service Unavailable');
			return;
		}

		this.activeRequests++;

		res.on('finish', () => {
			this.activeRequests--;
			if (this.isShuttingDown && this.activeRequests === 0 && this.resolveShutdown) {
				this.resolveShutdown();
			}
		});

		next();
	}

	async onApplicationShutdown(): Promise<void> {
		this.isShuttingDown = true;

		if (this.activeRequests > 0) {
			console.log(`Waiting for ${this.activeRequests} requests to complete`);
			this.shutdownPromise = new Promise((resolve) => {
				this.resolveShutdown = resolve;
			});

			// Wait with timeout
			await Promise.race([this.shutdownPromise, new Promise((resolve) => setTimeout(resolve, 30000))]);
		}

		console.log('All requests completed');
	}
}
```

Reference: [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)
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