1---
2title: Use Async Lifecycle Hooks Correctly
3impact: HIGH
4impactDescription: Improper async handling blocks application startup
5tags: performance, lifecycle, async, hooks
6---
7 
8## Use Async Lifecycle Hooks Correctly
9 
10NestJS 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.
11 
12**Incorrect (fire-and-forget async without await):**
13 
14```typescript
15// Fire-and-forget async without await
16@Injectable()
17export class DatabaseService implements OnModuleInit {
18  onModuleInit() {
19    // This runs but doesn't block - app starts before DB is ready!
20    this.connect();
21  }
22 
23  private async connect() {
24    await this.pool.connect();
25    console.log('Database connected');
26  }
27}
28 
29// Heavy blocking operations in constructor
30@Injectable()
31export class ConfigService {
32  private config: Config;
33 
34  constructor() {
35    // BLOCKS entire module instantiation synchronously
36    this.config = fs.readFileSync('config.json');
37  }
38}
39```
40 
41**Correct (return promises from async hooks):**
42 
43```typescript
44// Return promise from async hooks
45@Injectable()
46export class DatabaseService implements OnModuleInit {
47  private pool: Pool;
48 
49  async onModuleInit(): Promise<void> {
50    // NestJS waits for this to complete before continuing
51    await this.pool.connect();
52    console.log('Database connected');
53  }
54 
55  async onModuleDestroy(): Promise<void> {
56    // Clean up resources on shutdown
57    await this.pool.end();
58    console.log('Database disconnected');
59  }
60}
61 
62// Use onApplicationBootstrap for cross-module dependencies
63@Injectable()
64export class CacheWarmerService implements OnApplicationBootstrap {
65  constructor(
66    private cache: CacheService,
67    private products: ProductsService,
68  ) {}
69 
70  async onApplicationBootstrap(): Promise<void> {
71    // All modules are initialized, safe to warm cache
72    const products = await this.products.findPopular();
73    await this.cache.warmup(products);
74  }
75}
76 
77// Heavy init in async hooks, not constructor
78@Injectable()
79export class ConfigService implements OnModuleInit {
80  private config: Config;
81 
82  constructor() {
83    // Keep constructor synchronous and fast
84  }
85 
86  async onModuleInit(): Promise<void> {
87    // Async loading in lifecycle hook
88    this.config = await this.loadConfig();
89  }
90 
91  private async loadConfig(): Promise<Config> {
92    const file = await fs.promises.readFile('config.json');
93    return JSON.parse(file.toString());
94  }
95 
96  get<T>(key: string): T {
97    return this.config[key];
98  }
99}
100 
101// Enable shutdown hooks in main.ts
102async function bootstrap() {
103  const app = await NestFactory.create(AppModule);
104  app.enableShutdownHooks(); // Enable SIGTERM/SIGINT handling
105  await app.listen(3000);
106}
107```
108 
109Reference: [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)
110