Application lifecycle hooks in NestJS

This chapter follows Dynamic modules in NestJS.

The request lifecycle describes one request. The application lifecycle describes the process: Nest builds the module graph, creates every provider, starts listening, and, when told to stop, tears it all down again. Providers, controllers, and modules can implement hook interfaces to run code at each of these points. That is where a cache warms up, a consumer subscribes to a queue, and a connection is closed before the process exits.

The hooks in order

sequenceDiagram
  participant Main as main.ts
  participant Nest
  participant Svc as Your providers
  Main->>Nest: NestFactory.create(AppModule)
  Nest->>Svc: onModuleInit()
  Nest->>Svc: onApplicationBootstrap()
  Main->>Nest: app.listen()
  Note over Nest: Serving requests
  Nest->>Svc: onModuleDestroy()
  Nest->>Svc: beforeApplicationShutdown(signal)
  Note over Nest: HTTP server closes
  Nest->>Svc: onApplicationShutdown(signal)

Every hook may be async. Nest awaits the returned promise before it moves to the next step, so startup waits for an onModuleInit() that connects to a broker.

Running work at startup

Constructors should only store their dependencies. Work that is asynchronous, or that needs another provider to be fully set up, belongs in a hook:

1
import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
2
import { RatesClient } from './rates.client';
3

4
@Injectable()
5
export class ExchangeRatesService implements OnModuleInit {
6
  private readonly logger = new Logger(ExchangeRatesService.name);
7
  private rates = new Map<string, number>();
8

9
  constructor(private readonly client: RatesClient) {}
10

11
  async onModuleInit() {
12
    this.rates = await this.client.fetchAll();
13
    this.logger.log(`Loaded ${this.rates.size} exchange rates`);
14
  }
15
}

onModuleInit() runs per module, as soon as that module’s providers exist. onApplicationBootstrap() runs after every module is ready, so it is the safer hook for work that touches several modules, such as starting a scheduler that calls services from all over the app.

Cleaning up at shutdown

The destroy and shutdown hooks release what startup acquired: stop consuming from a queue, flush buffered logs or metrics, close a client.

1
import { Injectable, OnApplicationBootstrap, OnModuleDestroy } from '@nestjs/common';
2
import { QueueClient } from './queue.client';
3

4
@Injectable()
5
export class OrderConsumer implements OnApplicationBootstrap, OnModuleDestroy {
6
  constructor(private readonly queue: QueueClient) {}
7

8
  async onApplicationBootstrap() {
9
    await this.queue.subscribe('orders', (message) => this.handle(message));
10
  }
11

12
  async onModuleDestroy() {
13
    await this.queue.unsubscribe('orders');
14
  }
15

16
  private async handle(message: unknown) {}
17
}

Order matters here. Stop taking new work in onModuleDestroy(), let in-flight work finish, and close shared connections last, in onApplicationShutdown(). Library modules such as @nestjs/mongoose already close their own connections this way.

Enabling shutdown hooks

The destroy and shutdown hooks only run when Nest knows the process is stopping. app.close() triggers them. Signals such as SIGTERM do not, unless you opt in:

1
async function bootstrap() {
2
  const app = await NestFactory.create(AppModule);
3
  app.enableShutdownHooks();
4
  await app.listen(process.env.PORT ?? 3000);
5
}
6
bootstrap();

Without this line, a container platform that stops a pod with SIGTERM kills the process without calling any hook, and open connections are simply dropped. Nest leaves it off by default because each listener costs a little memory, and because several Nest apps in one process, as in some test setups, would each register their own. The platform’s grace period, 30 seconds by default on Kubernetes, is the upper bound for all shutdown hooks together.

Where hooks are not called

Hooks run for singleton providers, controllers, and modules. They are not called on request-scoped or transient providers, because those are created per request or per consumer, not at startup. A request-scoped provider that holds a resource has to release it some other way, typically by not holding long-lived resources at all.

Hooks also run in the order modules are initialized, which follows the import graph: a module’s dependencies are initialized before the module itself. Shutdown follows the reverse order. Do not rely on any order between two modules that do not depend on each other.

Next: MongoDB with Mongoose in NestJS.