From cf98db28d54bb4f5c1bccd8329bf9f8148c02586 Mon Sep 17 00:00:00 2001 From: Tony Bove Date: Thu, 23 Jul 2020 12:00:43 -1000 Subject: [PATCH] docs: Refactor module-types.md to make it easier to understand (#38206) Project DOCS-736 to rewrite headings to focus on user tasks, verify that the content is up-to-date and complete, and add relevant links to other NgModule topics to improve readability. Also addresses one of many issues in GitHub issue 21531. PR Close #38206 --- aio/content/guide/module-types.md | 258 ++++++++++++++++++------------ 1 file changed, 153 insertions(+), 105 deletions(-) diff --git a/aio/content/guide/module-types.md b/aio/content/guide/module-types.md index ceab1216cc..cd5aae56e9 100644 --- a/aio/content/guide/module-types.md +++ b/aio/content/guide/module-types.md @@ -1,116 +1,41 @@ -# Types of feature modules +# Guidelines for creating NgModules -There are five general categories of feature modules which -tend to fall into the following groups: +This topic provides a conceptual overview of the different categories of [NgModules](guide/glossary#ngmodule "Definition of NgModule") you can create in order to organize your code in a modular structure. +These categories are not cast in stone—they are suggestions. +You may want to create NgModules for other purposes, or combine the characteristics of some of these categories. -* Domain feature modules. -* Routed feature modules. -* Routing modules. -* Service feature modules. -* Widget feature modules. +NgModules are a great way to organize an app and keep code related to a specific functionality or feature separate from other code. +Use NgModules to consolidate [components](guide/glossary#component "Definition of component"), [directives](guide/glossary#directive "Definition of directive"), and [pipes](guide/glossary#pipe "Definition of pipe)") into cohesive blocks of functionality. +Focus each block on a feature or business domain, a workflow or navigation flow, a common collection of utilities, or one or more [providers](guide/glossary#provider "Definition of provider") for [services](guide/glossary#service "Definition of service"). -While the following guidelines describe the use of each type and their -typical characteristics, in real world apps, you may see hybrids. +For more about NgModules, see [Organizing your app with NgModules](guide/ngmodules "Organizing your app with NgModules"). - +
-
- +For the example app used in NgModules-related topics, see the . - - + - - - - - - - - - - - - - - - - - - - - - - - - -
- Feature Module - - Guidelines -
Domain - Domain feature modules deliver a user experience dedicated to a particular application domain like editing a customer or placing an order. +## Summary of NgModule categories - They typically have a top component that acts as the feature root and private, supporting sub-components descend from it. +All apps start by [bootstrapping a root NgModule](guide/bootstrapping "Launching an app with a root NgModule"). +You can organize your other NgModules any way you wish. - Domain feature modules consist mostly of declarations. Only the top component is exported. +This topic provides some guidelines for the following general categories of NgModules: - Domain feature modules rarely have providers. When they do, the lifetime of the provided services should be the same as the lifetime of the module. +* [Domain](#domain): A domain NgModule is organized around a feature, business domain, or user experience. +* [Routed](#routed): The top component of the NgModule acts as the destination of a [router](guide/glossary#router "Definition of router") navigation route. +* [Routing](#routing): A routing NgModule provides the routing configuration for another NgModule. +* [Service](#service): A service NgModule provides utility services such as data access and messaging. +* [Widget](#widget): A widget NgModule makes a component, directive, or pipe available to other NgModules. +* [Shared](#shared): A shared NgModule makes a set of components, directives, and pipes available to other NgModules. - Domain feature modules are typically imported exactly once by a larger feature module. - - They might be imported by the root `AppModule` of a small application that lacks routing. -
Routed - Routed feature modules are domain feature modules whose top components are the targets of router navigation routes. - - All lazy-loaded modules are routed feature modules by definition. - - Routed feature modules don’t export anything because their components never appear in the template of an external component. - - A lazy-loaded routed feature module should not be imported by any module. Doing so would trigger an eager load, defeating the purpose of lazy loading.That means you won’t see them mentioned among the `AppModule` imports. An eager loaded routed feature module must be imported by another module so that the compiler learns about its components. - - Routed feature modules rarely have providers for reasons explained in [Lazy Loading Feature Modules](/guide/lazy-loading-ngmodules). When they do, the lifetime of the provided services should be the same as the lifetime of the module. Don't provide application-wide singleton services in a routed feature module or in a module that the routed module imports. -
Routing - - A routing module provides routing configuration for another module and separates routing concerns from its companion module. - - A routing module typically does the following: - -
    -
  • Defines routes.
    • -
  • Adds router configuration to the module's imports.
    • -
  • Adds guard and resolver service providers to the module's providers.
    • -
  • The name of the routing module should parallel the name of its companion module, using the suffix "Routing". For example, FooModule in foo.module.ts has a routing module named FooRoutingModule in foo-routing.module.ts. If the companion module is the root AppModule, the AppRoutingModule adds router configuration to its imports with RouterModule.forRoot(routes). All other routing modules are children that import RouterModule.forChild(routes).
    • -
  • A routing module re-exports the RouterModule as a convenience so that components of the companion module have access to router directives such as RouterLink and RouterOutlet.
    • -
  • A routing module does not have its own declarations. Components, directives, and pipes are the responsibility of the feature module, not the routing module.
    • -
- - A routing module should only be imported by its companion module. - -
Service - - Service modules provide utility services such as data access and messaging. Ideally, they consist entirely of providers and have no declarations. Angular's `HttpClientModule` is a good example of a service module. - - The root `AppModule` is the only module that should import service modules. - -
Widget - - A widget module makes components, directives, and pipes available to external modules. Many third-party UI component libraries are widget modules. - - A widget module should consist entirely of declarations, most of them exported. - - A widget module should rarely have providers. - - Import widget modules in any module whose component templates need the widgets. - -
- -The following table summarizes the key characteristics of each feature module group. +The following table summarizes the key characteristics of each category. - + @@ -151,7 +76,7 @@ The following table summarizes the key characteristics of each feature module gr - + @@ -167,14 +92,137 @@ The following table summarizes the key characteristics of each feature module gr - + + + + + + + + +
- Feature Module + NgModule @@ -135,7 +60,7 @@ The following table summarizes the key characteristics of each feature module gr Yes Rare Top componentFeature, AppModuleAnother domain, AppModule
No Yes (Guards) RouterModuleFeature (for routing)Another domain (for routing)
Yes Rare YesFeatureAnother domain
SharedYesNoYesAnother domain
-
+{@a domain} -## More on NgModules +## Domain NgModules + +Use a domain NgModule to deliver a user experience dedicated to a particular feature or app domain, such as editing a customer or placing an order. +One example is `ContactModule` in the . + +A domain NgModule organizes the code related to a certain function, containing all of the components, routing, and templates that make up the function. +Your top component in the domain NgModule acts as the feature or domain's root, and is the only component you export. +Private supporting subcomponents descend from it. + +Import a domain NgModule exactly once into another NgModule, such as a domain NgModule, or into the root NgModule (`AppModule`) of an app that contains only a few NgModules. + +Domain NgModules consist mostly of declarations. +You rarely include providers. +If you do, the lifetime of the provided services should be the same as the lifetime of the NgModule. + +
+ +For more information about lifecycles, see [Hooking into the component lifecycle](guide/lifecycle-hooks "Hooking into the component lifecycle"). + +
+ +{@a routed} + +## Routed NgModules + +Use a routed NgModule for all [lazy-loaded NgModules](guide/lazy-loading-ngmodules "Lazy-loading an NgModule"). +Use the top component of the NgModule as the destination of a router navigation route. +Routed NgModules don’t export anything because their components never appear in the template of an external component. + +Don't import a lazy-loaded routed NgModule into another NgModule, as this would trigger an eager load, defeating the purpose of lazy loading. + +Routed NgModules rarely have providers because you load a routed NgModule only when needed (such as for routing). +Services listed in the NgModules' `provider` array would not be available because the root injector wouldn’t know about the lazy-loaded NgModule. +If you include providers, the lifetime of the provided services should be the same as the lifetime of the NgModule. +Don't provide app-wide [singleton services](guide/singleton-services) in a routed NgModule or in an NgModule that the routed NgModule imports. + +
+ +For more information about providers and lazy-loaded routed NgModules, see [Limiting provider scope](guide/providers#limiting-provider-scope-by-lazy-loading-modules "Providing dependencies: Limiting provider scope"). + +
+ +{@a routing} + +## Routing NgModules + +Use a routing NgModule to provide the routing configuration for a domain NgModule, thereby separating routing concerns from its companion domain NgModule. +One example is `ContactRoutingModule` in the , which provides the routing for its companion domain NgModule `ContactModule`. + +
+ +For an overview and details about routing, see [In-app navigation: routing to views](guide/router "In-app navigation: routing to views"). + +
+ +Use a routing NgModule to do the following tasks: + +* Define routes. +* Add router configuration to the NgModule's import. +* Add guard and resolver service providers to the NgModule's providers. + +The name of the routing NgModule should parallel the name of its companion NgModule, using the suffix `Routing`. +For example, ContactModule in contact.module.ts has a routing NgModule named ContactRoutingModule in contact-routing.module.ts. + +Import a routing NgModule only into its companion NgModule. +If the companion NgModule is the root AppModule, the AppRoutingModule adds router configuration to its imports with RouterModule.forRoot(routes). +All other routing NgModules are children that import RouterModule.forChild(routes). + +In your routing NgModule, re-export the RouterModule as a convenience so that components of the companion NgModule have access to router directives such as RouterLink and RouterOutlet. + +Don't use declarations in a routing NgModule. +Components, directives, and pipes are the responsibility of the companion domain NgModule, not the routing NgModule. + +{@a service} + +## Service NgModules + +Use a service NgModule to provide a utility service such as data access or messaging. +Ideal service NgModules consist entirely of providers and have no declarations. +Angular's `HttpClientModule` is a good example of a service NgModule. + +Use only the root `AppModule` to import service NgModules. + +{@a widget} + +## Widget NgModules + +Use a widget NgModule to make a component, directive, or pipe available to external NgModules. +Import widget NgModules into any NgModules that need the widgets in their templates. +Many third-party UI component libraries are provided as widget NgModules. + +A widget NgModule should consist entirely of declarations, most of them exported. +It would rarely have providers. + +{@a shared} + +## Shared NgModules + +Put commonly used directives, pipes, and components into one NgModule, typically named `SharedModule`, and then import just that NgModule wherever you need it in other parts of your app. +You can import the shared NgModule in your domain NgModules, including [lazy-loaded NgModules](guide/lazy-loading-ngmodules "Lazy-loading an NgModule"). +One example is `SharedModule` in the , which provides the `AwesomePipe` custom pipe and `HighlightDirective` directive. + +Shared NgModules should not include providers, nor should any of its imported or re-exported NgModules include providers. + +To learn how to use shared modules to organize and streamline your code, see [Sharing NgModules in an app](guide/sharing-ngmodules "Sharing NgModules in an app"). + +## Next steps You may also be interested in the following: -* [Lazy Loading Modules with the Angular Router](guide/lazy-loading-ngmodules). -* [Providers](guide/providers). + +* For more about NgModules, see [Organizing your app with NgModules](guide/ngmodules "Organizing your app with NgModules"). +* To learn more about the root NgModule, see [Launching an app with a root NgModule](guide/bootstrapping "Launching an app with a root NgModule"). +* To learn about frequently used Angular NgModules and how to import them into your app, see [Frequently-used modules](guide/frequent-ngmodules "Frequently-used modules"). +* For a complete description of the NgModule metadata properties, see [Using the NgModule metadata](guide/ngmodule-api "Using the NgModule metadata"). + +If you want to manage NgModule loading and the use of dependencies and services, see the following: + +* To learn about loading NgModules eagerly when the app starts, or lazy-loading NgModules asynchronously by the router, see [Lazy-loading feature modules](guide/lazy-loading-ngmodules). +* To understand how to provide a service or other dependency for your app, see [Providing Dependencies for an NgModule](guide/providers "Providing Dependencies for an NgModule"). +* To learn how to create a singleton service to use in NgModules, see [Making a service a singleton](guide/singleton-services "Making a service a singleton").