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/perf-async-hooks.md

View on GitHub
---
title: Use Async Lifecycle Hooks Correctly
impact: HIGH
impactDescription: Improper async handling blocks application startup
tags: performance, lifecycle, async, hooks
---

## Use Async Lifecycle Hooks Correctly

NestJS lifecycle hooks (`onModuleInit`, `onApplicationBootstrap`, etc.) support async operations. However, misusing them can block application startup or cause race conditions. Understand the lifecycle order and use hooks appropriately.

**Incorrect (fire-and-forget async without await):**

```typescript
// Fire-and-forget async without await
@Injectable()
export class DatabaseService implements OnModuleInit {
	onModuleInit() {
		// This runs but doesn't block - app starts before DB is ready!
		this.connect();
	}

	private async connect() {
		await this.pool.connect();
		console.log('Database connected');
	}
}

// Heavy blocking operations in constructor
@Injectable()
export class ConfigService {
	private config: Config;

	constructor() {
		// BLOCKS entire module instantiation synchronously
		this.config = fs.readFileSync('config.json');
	}
}
```

**Correct (return promises from async hooks):**

```typescript
// Return promise from async hooks
@Injectable()
export class DatabaseService implements OnModuleInit {
	private pool: Pool;

	async onModuleInit(): Promise<void> {
		// NestJS waits for this to complete before continuing
		await this.pool.connect();
		console.log('Database connected');
	}

	async onModuleDestroy(): Promise<void> {
		// Clean up resources on shutdown
		await this.pool.end();
		console.log('Database disconnected');
	}
}

// Use onApplicationBootstrap for cross-module dependencies
@Injectable()
export class CacheWarmerService implements OnApplicationBootstrap {
	constructor(
		private cache: CacheService,
		private products: ProductsService
	) {}

	async onApplicationBootstrap(): Promise<void> {
		// All modules are initialized, safe to warm cache
		const products = await this.products.findPopular();
		await this.cache.warmup(products);
	}
}

// Heavy init in async hooks, not constructor
@Injectable()
export class ConfigService implements OnModuleInit {
	private config: Config;

	constructor() {
		// Keep constructor synchronous and fast
	}

	async onModuleInit(): Promise<void> {
		// Async loading in lifecycle hook
		this.config = await this.loadConfig();
	}

	private async loadConfig(): Promise<Config> {
		const file = await fs.promises.readFile('config.json');
		return JSON.parse(file.toString());
	}

	get<T>(key: string): T {
		return this.config[key];
	}
}

// Enable shutdown hooks in main.ts
async function bootstrap() {
	const app = await NestFactory.create(AppModule);
	app.enableShutdownHooks(); // Enable SIGTERM/SIGINT handling
	await app.listen(3000);
}
```

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: 471kUpdated 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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated 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