Understanding Angular modules (NgModule) and their scopes

Cyrille Tuzi
Apr 7, 2017 · 5 min read

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.

A French version of this post is available here.

Why 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 is two kind 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

  • 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?

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?

Modules to import each time you need them

  • FormsModule / ReactiveFormsModule
  • MatXModule and other UI modules
  • any other module giving you components, directives or pipes

Modules to import only once

  • 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

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

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?

  • 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

Architecture in Angular projects

By the same author

Cyrille Tuzi

Written by

JavaScript and Angular trainer, PHP certified, @formationjs