Application Context and Lifecycle

Relevant source files

• integration/hello-world/e2e/force-console.spec.ts
• integration/hello-world/e2e/middleware-execute-order.spec.ts
• packages/common/interfaces/http/http-server.interface.ts
• packages/common/interfaces/modules/dynamic-module.interface.ts
• packages/common/interfaces/modules/provider.interface.ts
• packages/common/interfaces/nest-application-context-options.interface.ts
• packages/common/interfaces/nest-application-context.interface.ts
• packages/common/interfaces/scope-options.interface.ts
• packages/core/adapters/http-adapter.ts
• packages/core/injector/container.ts
• packages/core/injector/injector.ts
• packages/core/injector/instance-loader.ts
• packages/core/injector/instance-wrapper.ts
• packages/core/injector/module-ref.ts
• packages/core/injector/module.ts
• packages/core/injector/topology-tree/topology-tree.ts
• packages/core/injector/topology-tree/tree-node.ts
• packages/core/nest-application-context.ts
• packages/core/nest-application.ts
• packages/core/nest-factory.ts
• packages/core/scanner.ts
• packages/core/test/injector/container.spec.ts
• packages/core/test/injector/injector.spec.ts
• packages/core/test/injector/instance-wrapper.spec.ts
• packages/core/test/injector/module.spec.ts
• packages/core/test/scanner.spec.ts
• packages/core/test/utils/noop-adapter.spec.ts
• packages/microservices/exceptions/index.ts
• packages/microservices/exceptions/kafka-retriable-exception.ts
• packages/microservices/microservices-module.ts
• packages/microservices/nest-microservice.ts
• packages/platform-express/adapters/express-adapter.ts
• packages/platform-express/interfaces/nest-express-application.interface.ts
• packages/platform-express/interfaces/serve-static-options.interface.ts
• packages/platform-fastify/adapters/fastify-adapter.ts
• packages/platform-fastify/interfaces/nest-fastify-application.interface.ts
• packages/websockets/exceptions/index.ts
• sample/18-context/package.json

This document describes the application context structure and lifecycle management in NestJS, covering how applications are created, initialized, and terminated. This includes the bootstrapping process, lifecycle hooks, and shutdown mechanisms.

For information about dependency injection mechanics, see Dependency Injection System. For module structure and organization, see Module System.

---

Application Context Types

NestJS provides three main application context types, each serving different use cases while sharing a common foundation.

Sources: packages/core/nest-application-context.ts40-512 packages/core/nest-application.ts54-497 packages/microservices/nest-microservice.ts35-299

NestApplicationContext

The base context class providing core functionality for all application types.

Property	Type	Purpose
container	NestContainer	Holds all modules, providers, controllers
injector	Injector	Resolves dependencies and creates instances
isInitialized	boolean	Tracks initialization state
moduleCompiler	ModuleCompiler	Compiles module metadata

Key Methods:

• select<T>(module) - Navigate to a specific module context
• get<T>(typeOrToken) - Retrieve a singleton instance
• resolve<T>(typeOrToken, contextId) - Resolve a request-scoped instance
• init() - Initialize the application and call lifecycle hooks
• close() - Terminate the application gracefully

Sources: packages/core/nest-application-context.ts68-81

NestApplication

Extends NestApplicationContext with HTTP server capabilities.

Additional features:

• HTTP adapter integration (Express/Fastify)
• Middleware registration
• Route registration
• WebSocket and microservice hybrid support

Sources: packages/core/nest-application.ts54-109

NestMicroservice

Extends NestApplicationContext for microservice patterns.

Additional features:

• Transport layer integration (TCP, Redis, RabbitMQ, etc.)
• Message pattern handlers
• Event-driven communication

Sources: packages/microservices/nest-microservice.ts35-82

---

Application Bootstrapping Flow

The NestFactory class orchestrates the entire bootstrapping process.

Sources: packages/core/nest-factory.ts201-248

Bootstrapping Steps

1. Container Creation

The NestContainer is initialized with application configuration:

packages/core/nest-factory.ts88-90

2. Module Scanning

DependenciesScanner recursively scans modules, starting from the root module:

• Processes @Module() decorators
• Registers imports, providers, controllers, exports
• Builds dependency graph
• Calculates module distances

packages/core/scanner.ts86-104

3. Instance Loading

InstanceLoader creates instances of all registered providers and controllers:

• Loads prototypes
• Resolves dependencies
• Instantiates classes
• Applies property injection

packages/core/injector/instance-loader.ts27-82

Sources: packages/core/nest-factory.ts59-113 packages/core/scanner.ts75-104 packages/core/injector/instance-loader.ts18-82

---

Initialization Process

After bootstrapping, the application must be initialized via init() before it can handle requests.

Sources: packages/core/nest-application.ts176-197 packages/core/nest-application-context.ts253-271

Initialization Phases for HTTP Applications

Phase 1: HTTP Adapter Initialization

packages/core/nest-application.ts182

Phase 2: Body Parser Registration

packages/core/nest-application.ts186-199

Phase 3: Module Registration

Registers WebSocket, microservice, and middleware modules:

packages/core/nest-application.ts139-161

Phase 4: Router Registration

Routes are registered with the HTTP adapter:

packages/core/nest-application.ts205-211

Phase 5: Lifecycle Hooks

• onModuleInit hooks are called
• onApplicationBootstrap hooks are called

packages/core/nest-application.ts190-192

Sources: packages/core/nest-application.ts176-197

---

Lifecycle Hooks

NestJS provides five lifecycle hooks that providers, controllers, and modules can implement.

Hook Execution Order

Sources: packages/core/nest-application-context.ts422-480

Lifecycle Hook Interfaces

Hook	Interface	Timing	Use Case
onModuleInit	OnModuleInit	After all dependencies resolved	Initialize module-specific logic
onApplicationBootstrap	OnApplicationBootstrap	After all modules initialized	Perform application-wide setup
onModuleDestroy	OnModuleDestroy	Before module cleanup	Clean up module resources
beforeApplicationShutdown	BeforeApplicationShutdown	Before connections closed	Prepare for shutdown
onApplicationShutdown	OnApplicationShutdown	After connections closed	Final cleanup

Module Distance and Execution Order

Modules are assigned a "distance" value representing their depth in the module dependency tree. This determines hook execution order:

• Initialization hooks: Execute from closest to root (distance 0) to furthest
• Destruction hooks: Execute in reverse order (furthest to closest)
• Global modules: Always have distance Number.MAX_VALUE to ensure they initialize first

packages/core/scanner.ts397-416

Hook Invocation Implementation:

The getModulesToTriggerHooksOn() method sorts modules by distance:

packages/core/nest-application-context.ts490-504

For initialization:

For shutdown:

packages/core/nest-application-context.ts422-441

Sources: packages/core/scanner.ts397-416 packages/core/nest-application-context.ts422-504

---

Shutdown and Graceful Termination

NestJS supports graceful shutdown through process signals and explicit close methods.

Enabling Shutdown Hooks

Default Signals:

• SIGTERM
• SIGINT
• SIGHUP
• SIGBREAK (Windows)

packages/core/nest-application-context.ts324-346

Shutdown Sequence

Sources: packages/core/nest-application-context.ts277-284 packages/core/nest-application-context.ts361-404

Shutdown Hook Implementation

The shutdown listener is registered for each signal:

packages/core/nest-application-context.ts361-404

Cleanup Process:

1. Check for duplicate signals: If already shutting down, ignore
2. Call destroy hooks: onModuleDestroy() on all modules
3. Call before shutdown hooks: beforeApplicationShutdown(signal) with signal name
4. Dispose resources: Close HTTP server, WebSocket connections, microservice transports
5. Call shutdown hooks: onApplicationShutdown(signal) for final cleanup
6. Exit process: Either via process.exit(0) or process.kill(process.pid, signal)

packages/core/nest-application.ts97-108

Sources: packages/core/nest-application-context.ts277-284 packages/core/nest-application-context.ts361-404 packages/core/nest-application.ts97-108

---

Context Navigation and Instance Retrieval

The application context provides methods to navigate the module tree and retrieve instances.

Module Selection

The select() method navigates to a specific module:

Module Token Resolution:

packages/core/nest-application-context.ts92-130

The select() method:

1. Compiles the module to extract metadata
2. Creates a token using ModuleTokenFactory
3. Retrieves the module from the container
4. Returns a new NestApplicationContext scoped to that module

Sources: packages/core/nest-application-context.ts92-130

Instance Retrieval Methods

Method	Scope	Returns	Use Case
get<T>(token)	Singleton	Single instance	Retrieve DEFAULT scope providers
get<T>(token, {strict: true})	Current module only	Single instance	Strict module boundary
get<T>(token, {each: true})	All modules	Array of instances	Multiple registrations
resolve<T>(token)	REQUEST scope	New instance	Request-scoped providers
resolve<T>(token, contextId)	Custom context	Scoped instance	Custom DI context

Get Method Implementation:

packages/core/nest-application-context.ts136-175

Resolve Method Implementation:

packages/core/nest-application-context.ts181-237

The resolve() method:

1. Creates a new ContextId if not provided
2. Calls resolvePerContext() to get a request-scoped instance
3. Returns the instance from the specific context

Sources: packages/core/nest-application-context.ts136-237

Context ID and Request Scoping

Each request can have its own DI context via ContextId:

packages/core/injector/instance-wrapper.ts36-40

The registerRequestByContextId() method associates a request object with a context:

packages/core/nest-application-context.ts243-245

This enables REQUEST-scoped providers to access the current request object.

Sources: packages/core/injector/instance-wrapper.ts36-40 packages/core/nest-application-context.ts243-245

---

Preview Mode

NestJS supports a "preview mode" where providers are not instantiated but the module structure is built.

Preview Mode Configuration

Preview Mode Behavior:

• Module scanning occurs normally
• Dependency graph is constructed
• Providers are not instantiated
• Lifecycle hooks are not called (unless initOnPreview: true)
• Useful for inspection and testing

packages/core/nest-application-context.ts78-80

Init-on-Preview Flag

Modules can be marked to initialize even in preview mode:

packages/core/injector/container.ts163-169

This is useful for core infrastructure modules that must always initialize.

Sources: packages/core/nest-application-context.ts78-80 packages/core/nest-application-context.ts482-488 packages/core/nest-application-context.ts500-502 packages/core/injector/container.ts163-169

---

Application Context Internal Architecture

The context relies on several internal components working together.

Sources: packages/core/nest-application-context.ts68-81 packages/core/injector/container.ts31-60 packages/core/injector/module.ts44-160

Key Components

NestContainer

Central registry for all modules and configuration:

• Stores all Module instances in ModulesContainer
• Tracks global modules
• Holds dynamic module metadata
• Manages internal providers (HTTP adapter, etc.)
• Provides addModule(), addProvider(), addImport() methods

packages/core/injector/container.ts31-60

Module

Represents a single module with its providers and controllers:

• Maintains collections of providers, controllers, injectables
• Tracks imports and exports
• Has a unique ID and token
• Stores distance value for lifecycle ordering
• Provides ModuleRef for dependency retrieval

packages/core/injector/module.ts44-160

Injector

Handles dependency resolution and instantiation:

• Resolves constructor parameters
• Resolves property dependencies
• Handles circular dependencies
• Manages scope (DEFAULT, REQUEST, TRANSIENT)
• Creates instances via instantiateClass()

packages/core/injector/injector.ts86-107

InstanceWrapper

Wraps each provider/controller instance with metadata:

• Holds the actual instance
• Tracks resolution state (isResolved, isPending)
• Manages per-context instances (REQUEST scope)
• Stores dependency metadata
• Handles scope logic (static, request, transient)

packages/core/injector/instance-wrapper.ts61-98

Sources: packages/core/injector/container.ts31-60 packages/core/injector/module.ts44-160 packages/core/injector/injector.ts86-107 packages/core/injector/instance-wrapper.ts61-98

---

Sample Application: Context Usage

The sample application at sample/18-context demonstrates practical context usage patterns.

Key Dependencies:

sample/18-context/package.json21-26

This sample illustrates:

• Creating a standalone application context
• Retrieving instances without HTTP server
• Using lifecycle hooks
• Proper shutdown handling

Sources: sample/18-context/package.json1-48