Search across all documentation pages
NestJS looks, at first glance, like Express or Fastify with extra decorators - but its actual core abstraction is different in kind, not just in style: a graph of modules, wired together by an IoC (inversion of control) container, sitting on top of a swappable HTTP adapter that can be Express, Fastify, or something else entirely.
That's a meaningfully different starting point than "a chain of functions" or "a tree of plugins" - NestJS borrows its architecture from Angular's dependency injection system and applies it server-side, which is why teams coming from Spring Boot or Angular tend to find it immediately familiar, and teams coming from plain Express or Fastify tend to find the decorator-and-DI machinery unfamiliar at first.
This page is the mental model behind that machinery: what a module actually is, how the container resolves dependencies from decorator metadata, and how a request's journey through guards, interceptors, and pipes differs from a middleware chain or a plugin's lifecycle hooks.
NestJS Basics covers this hands-on with working modules and controllers; Dependency Injection goes deep on provider scopes and custom tokens built on top of the model described here.
A module, decorated with @Module(), is NestJS's unit of architecture: it declares which providers (services, repositories, anything injectable) it owns, which controllers handle its HTTP routes, and which other modules it imports or exports to share providers across boundaries.
@Module({
imports: [DatabaseModule],
controllers: [UsersController],
providers: [UsersService],
exports: [UsersService],
})
export class UsersModule {}Every application has exactly one root module (conventionally AppModule), and every other module connects to it, directly or indirectly, through imports - which is why the whole structure is accurately called a graph: modules are nodes, and imports are the edges connecting them.
The IoC container is what actually builds this graph at startup: instead of a UsersController constructing its own UsersService with new, it declares the dependency as a constructor parameter, and the container looks at that parameter's type, finds (or creates) the matching provider, and hands it in - "inversion of control" because the class no longer controls how its own dependencies come into existence.
A simple way to picture it: rather than each worker fetching their own tools from a shed, a foreman (the container) reads everyone's tool list ahead of time, assembles the tools, and delivers exactly what each worker declared they need before work starts.
The mechanism that makes constructor injection possible without any explicit registration code is decorator metadata: @Injectable(), @Controller(), and constructor parameter types are recorded, at compile time, via TypeScript's emitDecoratorMetadata and the reflect-metadata library - so by the time the container runs, it can read "this class's constructor needs a UsersService" directly from metadata attached to the class, without you writing any manual wiring.
This is a genuinely different mechanism from Express's shared-object mutation or Fastify's prototype-chained plugin scopes - nothing here happens by passing an object through a chain; it happens by the container inspecting compile-time-generated metadata and resolving a dependency graph before a single request arrives.
@Module() metadata declares providers/controllers/imports
│
▼
IoC container resolves the graph at bootstrap:
reads constructor parameter metadata (reflect-metadata)
instantiates providers in dependency order
injects resolved instances into each consumer
│
▼
NestFactory.create(AppModule, adapter) hands the resolved
app to an HTTP adapter (Express or Fastify) for transportThat last step is the adapter pattern at NestJS's core: NestJS itself is transport-agnostic - the module graph and DI container know nothing about HTTP specifically - and NestFactory.create() plugs in whichever adapter you choose (platform-express by default, or platform-fastify for better throughput) to actually accept connections and dispatch requests into the resolved graph.
Within a single request, NestJS layers a more elaborate pipeline than either underlying framework offers alone: middleware (adapter-level, Express- or Fastify-style) runs first, then guards (authorization decisions - can this request proceed at all), then interceptors (wrap the handler, can transform input or output), then pipes (validate and transform arguments), then the route handler itself, then interceptors again on the way out, with exception filters catching anything thrown along the way.
That fixed ordering - not middleware, then whatever you happen to write inline - is deliberate: it gives cross-cutting concerns (auth, validation, response shaping) a defined, predictable place to live instead of competing for position in one flat chain.
The module graph's biggest payoff shows up in testing and team scale: because every dependency arrives through the constructor rather than being imported and instantiated directly, Test.createTestingModule() can swap any provider for a mock with overrideProvider(), testing a controller or service in complete isolation from its real dependencies - something considerably more awkward to achieve cleanly in a flat Express chain or an unmanaged plugin tree.
The adapter pattern pays off beyond HTTP, too: because the module graph and DI container don't know anything HTTP-specific, the same architecture powers NestJS's microservices mode - swapping the HTTP adapter for a transport like TCP, Redis, or a message queue, while providers, guards, and the rest of the graph stay conceptually unchanged (see Microservices Mode).
Bootstrap cost is the trade-off that comes with all of this: resolving a large dependency graph, walking decorator metadata, and instantiating singleton providers takes real, measurable time and memory at startup - usually not a problem for a long-running server process, but a genuine consideration for cold-start-sensitive environments like serverless (see NestJS Performance Reality for the honest numbers).
Provider scope is the sharpest edge in the model: providers default to singleton (one instance for the whole app's lifetime), which is efficient but means anything request-specific - like a per-request user context - needs an explicit Scope.REQUEST opt-in, carrying its own re-instantiation cost per request that singleton providers don't pay.
| Framework's core abstraction | Strength | Weakness | Best Fit |
|---|---|---|---|
| NestJS: DI module graph | Enforced architecture; constructor-injected testability; transport-agnostic | Heaviest abstraction; real bootstrap cost; steepest learning curve | Large teams, long-lived enterprise services, mixed HTTP/microservice systems |
| Fastify: encapsulated plugin tree | Isolated scopes; schema-compiled dispatch for speed | No DI container; less enforced structure than modules | High-throughput or schema-first APIs |
| Express: flat middleware chain | Minimal, familiar, huge ecosystem | No encapsulation, no DI; structure is entirely convention | Small-to-medium CRUD APIs |
Scope.REQUEST providers are re-created per request, and that's an explicit, opt-in cost.reflect-metadata, which the IoC container reads at bootstrap to resolve the dependency graph - removing decorators would remove the container's ability to know what depends on what.A graph of modules - each declaring its own providers, controllers, and imports/exports - resolved at bootstrap by an IoC container that injects dependencies based on decorator-generated metadata.
No - NestJS itself is transport-agnostic. NestFactory.create() plugs in an adapter, typically Express (platform-express, the default) or Fastify (platform-fastify), to handle the actual HTTP transport underneath the resolved module graph.
From compile-time metadata generated by decorators (@Injectable(), @Controller()) and constructor parameter types, recorded via TypeScript's emitDecoratorMetadata and the reflect-metadata library - the container reads that metadata at bootstrap rather than requiring manual registration.
It's a class decorated with @Module() declaring which providers it owns, which controllers handle its routes, and which other modules' exported providers it imports - each module is one node in the application's overall dependency graph.
To give distinct cross-cutting concerns a defined, predictable place in a fixed pipeline - authorization decisions in guards, wrapping behavior in interceptors, argument validation in pipes - rather than competing for position in one undifferentiated middleware list.
By default, yes - one instance per application lifetime, resolved once at bootstrap. Request-specific state requires explicitly opting a provider into Scope.REQUEST, which re-instantiates it per request at additional cost.
Because the module graph and DI container are transport-agnostic, the same architecture backs NestJS's microservices mode - swapping the adapter for a non-HTTP transport (TCP, Redis, a message queue) while providers, guards, and the rest of the graph stay conceptually the same.
Resolving a full dependency graph - reading decorator metadata, instantiating singleton providers in the correct order - takes measurable time and memory before the server can accept its first request, unlike a flat middleware chain or plugin tree with comparatively little to resolve upfront.
For small services, prototypes, or teams that don't need enforced architecture and constructor-injected testability - the container, decorator metadata, and module boilerplate add real overhead that a flat Express chain or lean Fastify plugin tree avoids entirely.
Manual dependency passing (factory functions, closures) achieves similar testability without a container, but requires the team to enforce the discipline themselves - NestJS's container makes constructor injection the default, consistent pattern across the whole codebase.
A way to build a real module graph for tests while substituting any provider with overrideProvider().useValue() - so a controller or service can be tested against mocked dependencies without touching the real database, external API, or other providers it depends on.
No - modules give you an enforced dependency boundary, but you still decide how to group features into modules. Poor grouping (one giant module with everything in it) defeats the architecture's benefit even though the DI mechanism still technically works.
Stack versions: This page was written for NestJS 11 on Node.js 24 LTS, with TypeScript 5.6+.
Reviewed by Chris St. John·Last updated Jul 15, 2026