Understanding Angular modules (NgModule) and their scopes

NgModule is the first basic structure you meet when coding an app with Angular, but it’s also the most subtle and complex, because of different scopes. Angular documentation has done a whole FAQ about NgModules, but it’s still quite a mess to teach this during courses, students are often confused, so I decided to sum it up in this post for everyone.

Why NgModule?

It’s done automatically with Angular CLI, but the first thing you have to do in Angular is to load a root NgModule :

The purpose of a NgModule is to declare each thing you create in Angular, and group them together (like Java packages or PHP / C# namespaces).

There are two kinds of main structures:

• “declarations” is for things you’ll use in your templates: mainly components (~ views: the classes displaying data), but also directives and pipes,
• “providers” is for services (~ models: the classes getting and handling data).

Note: since Angular 6, services don’t need to be registered in a module anymore. The use of “providers” in a NgModule is now limited to overriding existing services.

NgModule and scopes / visibility

The confusion starts with components and services not having the same scope / visibility:

• declarations / components are in local scope (private visibility),
• providers / services are (generally) in global scope (public visibility).

It means the components you declared are only usable in the current module. If you need to use them outside, in other modules, you’ll have to export them:

On the contrary, services you provided will generally be available / injectable anywhere in your app, in all modules.

When to import a NgModule?

The difference of scope between components and services is an important point to know, but for now it’s still OK. Things get messy because, of course, as in any framework and app, you won’t just have one module, but many of them. Angular itself is subdivided in different modules (core, common, http and so on).

So another main thing you do in an Angular module is to import other NgModules you need:

Problem is: you need to know why you import these other modules.

• Is it to use components (or other template-related things, like directives and pipes)?
• or is is to use services?

Why? Because given the difference of scope between components and services :

• if the module is imported for components, you’ll need to import it in each module needing them,
• if the module is imported for services, you’ll need to import it only once, in the first app module.

If you fail to understand this, you’ll have errors on components not being available, because you forgot to import their module again.

Or if you import a module for services more than once, it can lead to errors in advanced scenarios like lazy-loading.

When to import main Angular modules?

A good knowledge of Angular modules is then required, to know how many times you need to import them. Here is an helpful summary.

Modules to import each time you need them

• CommonModule (all the basics of Angular templating: bindings, *ngIf, *ngFor…), except in the first app module, because it’s already part of the BrowserModule
• FormsModule / ReactiveFormsModule
• MatXModule and other UI modules
• any other module giving you components, directives or pipes

Modules to import only once

• HttpClientModule
• BrowserAnimationsModule or NoopAnimationsModule
• any other module providing you services only.

That’s why with Angular CLI, CommonModule is automatically imported when you create a new module.

Mixed NgModules

It can get messier: how to manage modules with components and services at the same time?

You know one of them : the RouterModule. It gives you a component (<router-outlet>) and a directive (routerLink), but also services (ActivatedRoute to get URL params, Router to navigate…).

Fortunately, the mess is managed by the module itself. Routing files are automatically generated by Angular CLI, but you may have noticed there is a subtle difference between the routing of your first app module and the routing of submodules.

For the AppModule, it does:

For submodules, it does:

Why? Because the first time in app module, forRoot() will give the router components and provide the router services. But the next times in submodules, forChild will only give the router components (and not providing again the services, which would be bad).

Lazy-loaded modules

Last complication : if you lazy-load a module, which is now easy with Angular CLI.

As it will be a different bundle and module, loaded only on demand by default, it’s not included in the global scope your app.

For components, it doesn’t change anything: you need to import again the CommonModule and other modules of components, like in any submodule.

For services, there is a difference:

• you’ll still have access to services already provided in the app (like HttpClient and your own services),
• but the services provided in your lazy-loaded module will only be available in this lazy-loaded module, not everywhere in your app.

Why?

Now you know everything about Angular modules, you may ask : why this mess ? Well, it may be difficult for beginners, but there is a good reason:

• services are mostly just ES6 classes : they are imported/exported, so in their namespaces, so no risk of collision! And singletons are usually what you want.
• components create… components, ie. new HTML tags : if they were global, loading two libraries creating components with the same name would create conflicts.

Summary

Your tree of imports (which is not exactly the same as your directories) should look like this:

Angular Schematics

If you want to save time when creating new components, services and else, give a try to my Angular Schematics extension for Visual Studio Code, installed nearly 1 million times.

Architecture in Angular projects

Want to know how to structure your own module in your Angular app? See the following post.