Application lifecycle in NestJS - Deep Dive

Overview - Application lifecycle

What is it?

The application lifecycle in NestJS is the series of steps an application goes through from start to finish. It includes initializing modules, creating providers, handling requests, and shutting down gracefully. This lifecycle helps manage how your app starts, runs, and stops in an organized way. It ensures your app resources are ready when needed and cleaned up properly when done.

Why it matters

Without a clear lifecycle, applications can start unpredictably, leak resources, or crash unexpectedly. The lifecycle solves these problems by giving developers control over each phase of the app's life. This means better performance, easier debugging, and safer shutdowns. Imagine a concert without a schedule—musicians would start playing at random times, causing chaos. The lifecycle is the schedule that keeps everything in harmony.

Where it fits

Before learning the application lifecycle, you should understand basic NestJS concepts like modules, controllers, and providers. After mastering the lifecycle, you can explore advanced topics like custom lifecycle hooks, middleware, and microservices integration. This topic sits at the core of building reliable and maintainable NestJS applications.

Mental Model

Core Idea

The application lifecycle is the controlled sequence of phases that manage how a NestJS app starts, runs, and stops smoothly.

Think of it like...

Think of the lifecycle like a theater play: first, the stage is set (initialization), then actors perform (handling requests), and finally, the curtains close and the stage is cleaned (shutdown).

┌───────────────┐
│ Initialization│
│ (Modules load)│
└──────┬────────┘
       │
┌──────▼────────┐
│  Running App  │
│(Handle Requests)│
└──────┬────────┘
       │
┌──────▼────────┐
│   Shutdown   │
│(Cleanup & Exit)│
└───────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding NestJS Modules

Concept: Modules are the building blocks of a NestJS app and start the lifecycle.

In NestJS, an application is divided into modules. Each module groups related controllers and providers. When the app starts, NestJS loads these modules to prepare the app structure. For example, an AppModule might import UserModule and AuthModule to organize features.

Result

The app has a clear structure where each module is ready to provide its services.

Knowing modules are the first step helps you see how the app organizes itself before doing any work.

2

Foundation

Providers and Dependency Injection

Concept: Providers are services created and managed during app startup to be used anywhere via injection.

Providers are classes that NestJS creates instances of during initialization. They can be injected into controllers or other providers. This means you don't create them manually; NestJS handles their lifecycle. For example, a UserService provider is created once and shared.

Result

Providers are ready and available throughout the app after startup.

Understanding providers explains how NestJS manages shared services efficiently during the lifecycle.

3

Intermediate

Lifecycle Hooks in NestJS

🤔Before reading on: do you think lifecycle hooks run automatically or need manual calls? Commit to your answer.

Concept: NestJS offers special methods called lifecycle hooks that run at specific phases automatically.

Lifecycle hooks like OnModuleInit, OnApplicationBootstrap, and OnModuleDestroy let you run code at key moments. For example, OnModuleInit runs after a module's providers are created, letting you initialize resources. OnModuleDestroy runs before shutdown to clean up.

Result

You can run custom code exactly when the app starts or stops.

Knowing hooks exist lets you control app behavior precisely during startup and shutdown.

4

Intermediate

Application Bootstrap Process

🤔Before reading on: does bootstrap only start the app or also prepare modules and providers? Commit to your answer.

Concept: Bootstrap is the function that starts the app, loading modules and creating providers.

The main.ts file calls NestFactory.create(AppModule) to bootstrap the app. This triggers loading all modules, creating providers, and setting up the HTTP server. Bootstrap is the entry point to the lifecycle.

Result

The app is fully initialized and ready to handle requests.

Understanding bootstrap clarifies how the app moves from code to a running server.

5

Advanced

Graceful Shutdown Handling

🤔Before reading on: do you think shutdown just kills the app or can it clean resources first? Commit to your answer.

Concept: NestJS supports graceful shutdown to clean resources before the app stops.

By implementing OnApplicationShutdown or OnModuleDestroy hooks, you can close database connections or stop background tasks before the app exits. NestJS listens for signals like SIGINT and runs these hooks to avoid abrupt stops.

Result

The app releases resources properly, preventing data loss or corruption.

Knowing graceful shutdown prevents common bugs in production apps related to resource leaks.

6

Expert

Custom Lifecycle Hook Implementation

🤔Before reading on: can you create your own lifecycle hooks beyond the built-in ones? Commit to your answer.

Concept: You can create custom lifecycle hooks by combining existing hooks and event emitters for complex app needs.

Advanced apps sometimes need custom phases, like delayed initialization or staged shutdown. By using event emitters inside OnModuleInit or OnApplicationShutdown, you can build your own lifecycle steps. This helps coordinate complex workflows or microservices.

Result

Your app lifecycle can adapt to unique requirements beyond defaults.

Understanding how to extend lifecycle hooks unlocks powerful customization for large-scale apps.

Under the Hood

NestJS uses a dependency injection container to manage providers and modules. During bootstrap, it recursively loads modules, resolves dependencies, and creates provider instances. Lifecycle hooks are detected via metadata and called automatically at the right time. Shutdown signals trigger cleanup hooks before the process exits.

Why designed this way?

This design separates concerns clearly: modules organize code, providers manage services, and hooks control lifecycle phases. It allows flexibility, testability, and scalability. Alternatives like manual service creation or global singletons were rejected because they cause tight coupling and harder maintenance.

┌───────────────┐
│ Bootstrap App │
└──────┬────────┘
       │
┌──────▼────────┐
│ Load Modules  │
└──────┬────────┘
       │
┌──────▼────────┐
│ Create Providers│
└──────┬────────┘
       │
┌──────▼────────┐
│ Call Init Hooks│
└──────┬────────┘
       │
┌──────▼────────┐
│ Run App Server│
└──────┬────────┘
       │
┌──────▼────────┐
│ Listen Shutdown│
│   Signals     │
└──────┬────────┘
       │
┌──────▼────────┐
│ Call Destroy Hooks│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does OnModuleInit run before or after all modules are loaded? Commit to your answer.

Common Belief: OnModuleInit runs after the entire application is fully ready.

Reality: OnModuleInit runs after the specific module's providers are created but before the whole app is ready.

Why it matters: Misunderstanding this can cause initialization code to run too early or too late, leading to bugs or race conditions.

Quick: Does NestJS automatically close database connections on shutdown? Commit to your answer.

Common Belief: NestJS automatically cleans up all resources like database connections on shutdown.

Reality: You must explicitly close resources in lifecycle hooks; NestJS does not do this automatically.

Why it matters: Failing to close resources can cause memory leaks or locked connections in production.

Quick: Can you call lifecycle hooks manually anytime? Commit to your answer.

Common Belief: Lifecycle hooks can be called manually whenever needed.

Reality: Lifecycle hooks are called automatically by NestJS at specific lifecycle phases and should not be called manually.

Why it matters: Calling hooks manually breaks the lifecycle flow and can cause inconsistent app states.

Quick: Is the bootstrap function only about starting the HTTP server? Commit to your answer.

Common Belief: Bootstrap only starts the HTTP server and nothing else.

Reality: Bootstrap initializes modules, creates providers, sets up middleware, and then starts the server.

Why it matters: Thinking bootstrap only starts the server leads to missing important initialization steps.

Expert Zone

1

Lifecycle hooks run per module, so the order matters when modules depend on each other.

2

Providers created as singletons share state across the app, which can cause subtle bugs if mutated unexpectedly.

3

Graceful shutdown hooks must complete quickly; long-running cleanup can delay app termination and cause timeouts.

When NOT to use

Avoid relying solely on lifecycle hooks for complex asynchronous workflows; use event-driven patterns or message queues instead. For very simple scripts, a full NestJS lifecycle may be overkill; plain Node.js might suffice.

Production Patterns

In production, lifecycle hooks are used to connect to databases on startup and close connections on shutdown. Apps often implement health checks during bootstrap and use graceful shutdown to handle signals from container orchestrators like Kubernetes.

Connections

Operating System Process Lifecycle

Both manage phases from start to stop with initialization and cleanup steps.

Understanding OS process lifecycle helps grasp why apps need controlled startup and graceful shutdown to avoid resource leaks.

Event-Driven Architecture

Lifecycle hooks act like events triggered at specific phases, similar to event-driven systems.

Knowing event-driven design clarifies how lifecycle hooks enable modular and reactive app behavior.

Theater Production Management

Both involve planned sequences: setup, performance, and teardown.

Seeing lifecycle as a production schedule highlights the importance of timing and order in app phases.

Common Pitfalls

#1 Not closing database connections on shutdown.

Wrong approach:

export class AppService implements OnApplicationShutdown {
onApplicationShutdown() {
// forgot to close DB connection
}
}

Correct approach:

export class AppService implements OnApplicationShutdown {
constructor(private readonly dbService: DbService) {}
async onApplicationShutdown() {
await this.dbService.closeConnection();
}
}

Root cause:

Assuming NestJS handles resource cleanup automatically without explicit code.

#2 Calling lifecycle hooks manually inside services.

Wrong approach:

someService.onModuleInit(); // manual call inside code

Correct approach:

// Let NestJS call onModuleInit automatically; do not call manually

Root cause:

Misunderstanding lifecycle hooks as regular methods instead of framework-managed callbacks.

#3 Running heavy initialization in constructor instead of OnModuleInit.

Wrong approach:

constructor() {
this.loadBigData(); // heavy work in constructor
}

Correct approach:

async onModuleInit() {
await this.loadBigData(); // defer heavy work to lifecycle hook
}

Root cause:

Not knowing constructors should be lightweight and initialization belongs in lifecycle hooks.

Key Takeaways

The NestJS application lifecycle controls how your app starts, runs, and stops in a clear sequence.

Modules and providers are created during bootstrap, setting up the app structure and services.

Lifecycle hooks let you run code automatically at key moments like initialization and shutdown.

Graceful shutdown is essential to clean up resources and avoid production bugs.

Advanced apps can customize lifecycle behavior by combining hooks and events for complex workflows.