NestJS Module Encapsulation Explained (with Cheat Sheet)

A NestJS app boots cleanly for weeks. Then a teammate adds NotificationsModule, wires NotificationsService into OrdersService's constructor, runs the app — and Nest refuses to start:

Nothing about NotificationsService itself is wrong — it's decorated with @Injectable(), it compiles, its own tests pass in isolation. The teammate even double-checked it's listed in NotificationsModule's providers array. It is. That's not the part that's missing.

By the end of this article you'll be able to:

You've built at least one multi-module NestJS app — a couple of feature modules, each with its own controller and service. You don't need to have hit the error above yet; we'll build it from nothing and then fix it properly.

This article is written against NestJS 12.x (verified against the nestjs/nest GitHub release history — v12.0.0 shipped August 27, 2026). Module registration, exports, @Global(), and forwardRef() are core-container behavior, unchanged in shape across the 10.x → 12.x line.

If you haven't read it yet, the previous episode covers how the DI container resolves providers and what "singleton" really means — this article assumes that mental model and builds the module-level picture on top of it, but you don't need it to follow along here.

Here's the setup, trimmed to the part that matters:

Everything here looks correct by the checklist most people carry around: @Injectable() on the service, listed in a module's providers, that module imported by the consumer. And yet Nest still can't resolve it — because the checklist is missing one line: NotificationsModule never says exports: [NotificationsService].

The mental model: a NestJS module isn't an organizational folder — it's a real wall around a slice of the DI container. Each module gets its own injector, and that injector only knows two kinds of providers: the ones listed directly in its own providers array, and the ones explicitly handed to it through imports — and only the subset of those that the imported module put in its own exports array.

providers answers "what can this module build?" exports answers a completely different question: "what am I willing to hand to whoever imports me?" A provider can be fully registered and working inside its own module and still be completely invisible to every other module, because providers alone doesn't open the wall — only exports does.

That's exactly the gap in the bug above: NotificationsModule builds NotificationsService correctly for its own internal use, but never lists it in exports. OrdersModule imports NotificationsModule — establishing an edge in the module graph — but that edge carries nothing across it, because the sending side never put anything on the wire.

Key concept: imports opens a door between two modules; exports decides what's allowed to walk through it. A provider needs both — registered somewhere, and exported from wherever it's registered — before another module's injector can see it, no matter how correctly it's decorated.

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

A module with nothing exported is still a perfectly valid, fully functional module — for its own controllers and services:

OrdersController and OrdersService can inject OrdersRepository freely — they're all in the same injector. Nothing here needs an export, because nothing here needs to leave the module. The boundary only becomes visible the moment something outside OrdersModule wants in.

exports takes a subset of what's in providers (or a whole imported module — see the next stage) and makes it resolvable by any module that lists this one in its own imports:

Only OrdersService is importable from elsewhere. OrdersRepository is an implementation detail — other modules that import OrdersModule get access to the service's public surface, not the repository it happens to use internally. This is deliberate, and it's the same instinct as a private class member: export the smallest set that satisfies every real consumer.

A module can also export a module it imported, without re-listing its individual providers — this passes the whole thing through:

Anything that imports SharedModule now has access to whatever CacheModule itself exports, without needing to import CacheModule directly. This is useful for grouping a handful of foundational modules into one convenience import — but it's also a coupling decision: every consumer of SharedModule now implicitly depends on CacheModule's public surface too, even if they only wanted one of the other things SharedModule re-exports.

Key concept: re-exporting is transitive on purpose. Use it to flatten a genuinely related group of modules into one import, not as a way to avoid writing imports: [ModuleA, ModuleB, ModuleC] explicitly when the three aren't actually related.

Some providers really do belong everywhere — a config service, a logger. Re-importing a ConfigModule into every single feature module works, but it's repetitive. @Global() exists for exactly this:

Once ConfigModule is imported once, anywhere in the module tree (typically AppModule), ConfigService becomes resolvable from every other module's injector, with no imports: [ConfigModule] needed at each call site. @Global() doesn't skip registration — the module still has to be imported once, and it still has to export what it wants global — it only skips the repeated importing everywhere else.

This is a real convenience, and it's also a real cost: every module in the app is now implicitly coupled to that provider, with no imports line anywhere marking the dependency. Reading OrdersModule's @Module() decorator no longer tells you everything OrdersService can inject — some of it is invisible, wired in from wherever @Global() was declared. That's fine for two or three truly cross-cutting providers (config, a logger); it stops being fine the moment @Global() becomes the answer to "I don't want to write another import."

forRoot() and forFeature() — the pattern behind ConfigModule.forRoot(...), TypeOrmModule.forFeature([...]), and most third-party Nest modules — are just regular functions that return a module definition object at runtime instead of a static @Module() class body:

Everything from Stages 1–3 applies unchanged: whatever this returns for exports is exactly as visible to importers as a static module's exports array, and whatever it leaves out is exactly as private. The only thing dynamic is when the module shape is decided — at imports: [DatabaseModule.forRoot({ url: '...' })] time, using arguments the static form can't accept — not whether encapsulation applies to the result.

Sometimes two modules genuinely need each other — UsersModule needs PostsModule to look up a user's posts, and PostsModule needs UsersModule to look up a post's author. Importing each other directly deadlocks Nest's bootstrap: to build UsersModule it needs PostsModule fully built first, which needs UsersModule fully built first.

forwardRef() tells Nest "reference this module, but don't try to fully resolve it yet" — it breaks the deadlock by deferring the reference instead of demanding it eagerly. Both sides of a module-level circular dependency need forwardRef(), not just one; wrapping only one side still leaves the other side trying to eagerly resolve something that isn't ready.

The same tool exists at the provider level, for a circular dependency between two services rather than two modules:

NestJS's own documentation is explicit that once forwardRef() is involved, the order of instantiation between the two sides is indeterminate — don't write constructor logic that assumes one of them is fully ready before the other's constructor has run.

Key concept: forwardRef() is a real fix for a real, occasional need — but a circular dependency between two modules is usually the container telling you two modules are actually one responsibility split awkwardly in half. Before reaching for forwardRef(), check whether the piece both sides need (in the example above, "which user wrote which post") belongs in a third module that both UsersModule and PostsModule import, with no circle at all.

Think it clicked? Take the 9-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

Nest's resolver doesn't distinguish the two causes in its message because, from the injector's point of view, they look identical: the token simply isn't visible in the context it's being asked for. Whether the root cause is a missing imports or a missing exports, check both.

No. exports only changes visibility, not instantiation — the provider is still built once, wherever it's registered in providers. This is the same rule the DI-container episode covers for sharing an instance across modules; exports is the mechanism that makes that sharing possible.

No — a module can only export a provider it registered itself, or a whole module it imported (Stage 3's re-export). You can't export a provider that belongs to some other module without going through that module's own module-level export.

It doesn't change how many instances exist — a global provider still follows the same Scope.DEFAULT/REQUEST/TRANSIENT rules as any other provider. @Global() only changes visibility: every module's injector can resolve it without an explicit imports line.

Yes — the circular dependency is between the two classes, not the modules, so it needs @Inject(forwardRef(() => OtherService)) on both constructors regardless of whether they live in the same @Module() or different ones.

The NotificationsService error from the top of this article is a one-line fix — add exports: [NotificationsService] — but the message Nest prints doesn't tell you which half of the contract is missing. Once "a module is a boundary, and only exports opens it" replaces "it's decorated with @Injectable(), so it should just work," that error stops being a mystery and starts being the first thing you check.

What's the module-boundary bug that cost you the most time — a missing export, an accidental @Global(), or a circular dependency you routed around with forwardRef() instead of fixing? Drop it in the comments.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected: