diff --git a/aio/content/examples/ngmodules/src/app/items/items.component.spec.ts b/aio/content/examples/ngmodules/src/app/items/items.component.spec.ts
new file mode 100644
index 0000000000..b77cce74ec
--- /dev/null
+++ b/aio/content/examples/ngmodules/src/app/items/items.component.spec.ts
@@ -0,0 +1,25 @@
+import { async, ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { ItemsComponent } from './items.component';
+
+describe('ItemsComponent', () => {
+ let component: ItemsComponent;
+ let fixture: ComponentFixture;
+
+ beforeEach(async(() => {
+ TestBed.configureTestingModule({
+ declarations: [ ItemsComponent ]
+ })
+ .compileComponents();
+ }));
+
+ beforeEach(() => {
+ fixture = TestBed.createComponent(ItemsComponent);
+ component = fixture.componentInstance;
+ fixture.detectChanges();
+ });
+
+ it('should create', () => {
+ expect(component).toBeTruthy();
+ });
+});
diff --git a/aio/content/examples/ngmodules/src/app/items/items.component.ts b/aio/content/examples/ngmodules/src/app/items/items.component.ts
new file mode 100644
index 0000000000..26696de194
--- /dev/null
+++ b/aio/content/examples/ngmodules/src/app/items/items.component.ts
@@ -0,0 +1,15 @@
+import { Component, OnInit } from '@angular/core';
+
+@Component({
+ selector: 'app-items',
+ templateUrl: './items.component.html',
+ styleUrls: ['./items.component.css']
+})
+export class ItemsComponent implements OnInit {
+
+ constructor() { }
+
+ ngOnInit() {
+ }
+
+}
diff --git a/aio/content/examples/ngmodules/src/app/items/items.module.ts b/aio/content/examples/ngmodules/src/app/items/items.module.ts
new file mode 100644
index 0000000000..b0f2b3f289
--- /dev/null
+++ b/aio/content/examples/ngmodules/src/app/items/items.module.ts
@@ -0,0 +1,14 @@
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+import { ItemsListComponent } from './items-list.component';
+import { ItemsDetailComponent } from './items-detail.component';
+import { ItemService } from './items.service';
+import { ItemsRoutingModule } from './items-routing.module';
+
+@NgModule({
+ imports: [ CommonModule, ItemsRoutingModule ],
+ declarations: [ ItemsDetailComponent, ItemsListComponent ],
+ providers: [ ItemService ]
+})
+export class ItemsModule {}
diff --git a/aio/content/examples/ngmodules/src/app/items/items.service.ts b/aio/content/examples/ngmodules/src/app/items/items.service.ts
new file mode 100644
index 0000000000..57b39e4ed3
--- /dev/null
+++ b/aio/content/examples/ngmodules/src/app/items/items.service.ts
@@ -0,0 +1,37 @@
+import { Injectable, OnDestroy } from '@angular/core';
+
+import { Observable } from 'rxjs/Observable';
+import { of } from 'rxjs/observable/of';
+import { delay } from 'rxjs/operator/delay';
+
+export class Item {
+ constructor(public id: number, public name: string) { }
+}
+
+const ITEMS: Item[] = [
+ new Item(1, 'Sticky notes'),
+ new Item(2, 'Dry erase markers'),
+ new Item(3, 'Erasers'),
+ new Item(4, 'Whiteboard cleaner'),
+];
+
+const FETCH_LATENCY = 500;
+
+/** Simulate a data service that retrieves crises from a server */
+@Injectable()
+export class ItemService implements OnDestroy {
+
+ constructor() { console.log('ItemService instance created.'); }
+ ngOnDestroy() { console.log('ItemService instance destroyed.'); }
+
+ getItems(): Observable {
+ return delay.call(of(ITEMS), FETCH_LATENCY);
+ }
+
+ getItem(id: number | string): Observable {
+ const item$ = of(ITEMS.find(item => item.id === +id));
+ return delay.call(item$, FETCH_LATENCY);
+ }
+}
+
+
diff --git a/aio/content/examples/ngmodules/src/app/shared/awesome.pipe.ts b/aio/content/examples/ngmodules/src/app/shared/awesome.pipe.ts
new file mode 100644
index 0000000000..ffe4949f21
--- /dev/null
+++ b/aio/content/examples/ngmodules/src/app/shared/awesome.pipe.ts
@@ -0,0 +1,9 @@
+import { Pipe, PipeTransform } from '@angular/core';
+
+@Pipe({ name: 'awesome' })
+/** Precede the input string with the word "Awesome " */
+export class AwesomePipe implements PipeTransform {
+ transform(phrase: string) {
+ return phrase ? 'Awesome ' + phrase : '';
+ }
+}
diff --git a/aio/content/examples/ngmodules/src/app/shared/highlight.directive.ts b/aio/content/examples/ngmodules/src/app/shared/highlight.directive.ts
new file mode 100644
index 0000000000..7210ddbf16
--- /dev/null
+++ b/aio/content/examples/ngmodules/src/app/shared/highlight.directive.ts
@@ -0,0 +1,13 @@
+/* tslint:disable */
+// Exact copy of contact/highlight.directive except for color and message
+import { Directive, ElementRef } from '@angular/core';
+
+@Directive({ selector: '[highlight], input' })
+/** Highlight the attached element or an InputElement in gray */
+export class HighlightDirective {
+ constructor(el: ElementRef) {
+ el.nativeElement.style.backgroundColor = '#efeeed';
+ console.log(
+ `* Shared highlight called for ${el.nativeElement.tagName}`);
+ }
+}
diff --git a/aio/content/examples/ngmodules/src/app/shared/shared.module.ts b/aio/content/examples/ngmodules/src/app/shared/shared.module.ts
new file mode 100644
index 0000000000..477f170c12
--- /dev/null
+++ b/aio/content/examples/ngmodules/src/app/shared/shared.module.ts
@@ -0,0 +1,14 @@
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { FormsModule } from '@angular/forms';
+
+import { AwesomePipe } from './awesome.pipe';
+import { HighlightDirective } from './highlight.directive';
+
+@NgModule({
+ imports: [ CommonModule ],
+ declarations: [ AwesomePipe, HighlightDirective ],
+ exports: [ AwesomePipe, HighlightDirective,
+ CommonModule, FormsModule ]
+})
+export class SharedModule { }
diff --git a/aio/content/examples/ngmodules/src/index.html b/aio/content/examples/ngmodules/src/index.html
new file mode 100644
index 0000000000..5e908028fe
--- /dev/null
+++ b/aio/content/examples/ngmodules/src/index.html
@@ -0,0 +1,14 @@
+
+
+
+
+ NgmodulesExample
+
+
+
+
+
+
+ Loading...
+
+
diff --git a/aio/content/examples/ngmodules/src/main.ts b/aio/content/examples/ngmodules/src/main.ts
new file mode 100644
index 0000000000..a9ca1caf8c
--- /dev/null
+++ b/aio/content/examples/ngmodules/src/main.ts
@@ -0,0 +1,11 @@
+import { enableProdMode } from '@angular/core';
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app/app.module';
+import { environment } from './environments/environment';
+
+if (environment.production) {
+ enableProdMode();
+}
+
+platformBrowserDynamic().bootstrapModule(AppModule);
diff --git a/aio/content/examples/providers/e2e/app.e2e-spec.ts b/aio/content/examples/providers/e2e/app.e2e-spec.ts
new file mode 100644
index 0000000000..46108fd9dc
--- /dev/null
+++ b/aio/content/examples/providers/e2e/app.e2e-spec.ts
@@ -0,0 +1,37 @@
+import { AppPage } from './app.po';
+import { browser, element, by } from 'protractor';
+
+describe('providers App', () => {
+ let page: AppPage;
+
+ beforeEach(() => {
+ page = new AppPage();
+ });
+
+ function getUsersStruct() {
+ return {
+ user: element.all(by.css('ng-component li')).get(0),
+ userId: element.all(by.css('ng-component span')).get(0)
+ };
+ }
+
+ function getListSectionStruct() {
+ return {
+ items: element.all(by.css('app-root li'))
+ };
+ }
+
+ it('should display header that says Users list', () => {
+ page.navigateTo();
+ expect(page.getParagraphText()).toEqual('Users list');
+ });
+
+
+ it('shows a list of customers', function() {
+ const list = getListSectionStruct();
+ expect(list.items.count()).toBe(10);
+ expect(list.items.get(0).getText()).toBe('1 Maria');
+ expect(list.items.get(9).getText()).toBe('10 Seth');
+ });
+
+});
diff --git a/aio/content/examples/providers/example-config.json b/aio/content/examples/providers/example-config.json
new file mode 100644
index 0000000000..313764c3c6
--- /dev/null
+++ b/aio/content/examples/providers/example-config.json
@@ -0,0 +1,4 @@
+{
+ "build": "build:cli",
+ "run": "serve:cli"
+}
diff --git a/aio/content/examples/providers/plnkr.json b/aio/content/examples/providers/plnkr.json
new file mode 100644
index 0000000000..516f516685
--- /dev/null
+++ b/aio/content/examples/providers/plnkr.json
@@ -0,0 +1,11 @@
+{
+ "description": "Providers",
+ "basePath": "src/",
+ "files": [
+ "!**/*.d.ts",
+ "!**/*.js",
+ "!**/*.[1,2].*"
+ ],
+ "open": "app/app.component.ts",
+ "tags": ["providers"]
+}
diff --git a/aio/content/examples/providers/src/app/app.component.css b/aio/content/examples/providers/src/app/app.component.css
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/aio/content/examples/providers/src/app/app.component.html b/aio/content/examples/providers/src/app/app.component.html
new file mode 100644
index 0000000000..7763b93ba8
--- /dev/null
+++ b/aio/content/examples/providers/src/app/app.component.html
@@ -0,0 +1,7 @@
+
+ {{title}}
+
+
+
+{{user.id}} {{user.name}}
+
diff --git a/aio/content/examples/providers/src/app/app.component.spec.ts b/aio/content/examples/providers/src/app/app.component.spec.ts
new file mode 100644
index 0000000000..13c632d676
--- /dev/null
+++ b/aio/content/examples/providers/src/app/app.component.spec.ts
@@ -0,0 +1,32 @@
+import { TestBed, async } from '@angular/core/testing';
+import { AppComponent } from './app.component';
+
+describe('AppComponent', () => {
+ beforeEach(() => {
+ TestBed.configureTestingModule({
+ declarations: [
+ AppComponent
+ ],
+ });
+ TestBed.compileComponents();
+ });
+
+ it('should create the app', async(() => {
+ const fixture = TestBed.createComponent(AppComponent);
+ const app = fixture.debugElement.componentInstance;
+ expect(app).toBeTruthy();
+ }));
+
+ it(`should have as title 'app works!'`, async(() => {
+ const fixture = TestBed.createComponent(AppComponent);
+ const app = fixture.debugElement.componentInstance;
+ expect(app.title).toEqual('app works!');
+ }));
+
+ it('should render title in a h1 tag', async(() => {
+ const fixture = TestBed.createComponent(AppComponent);
+ fixture.detectChanges();
+ const compiled = fixture.debugElement.nativeElement;
+ expect(compiled.querySelector('h1').textContent).toContain('app works!');
+ }));
+});
diff --git a/aio/content/examples/providers/src/app/app.component.ts b/aio/content/examples/providers/src/app/app.component.ts
new file mode 100644
index 0000000000..6310358a06
--- /dev/null
+++ b/aio/content/examples/providers/src/app/app.component.ts
@@ -0,0 +1,26 @@
+import { Component, OnInit } from '@angular/core';
+
+import { User } from './core/user';
+import { UserService } from './core/user.service';
+
+@Component({
+ selector: 'app-root',
+ templateUrl: './app.component.html',
+ styleUrls: ['./app.component.css'],
+ providers: [UserService]
+})
+export class AppComponent implements OnInit {
+ title = 'Users list';
+ users: User[];
+
+ constructor(private userService: UserService) { }
+
+ getUsers(): void {
+ this.userService.getUsers().then(users => this.users = users);
+ }
+
+ ngOnInit(): void {
+ this.getUsers();
+ }
+
+}
diff --git a/aio/content/examples/providers/src/app/app.module.ts b/aio/content/examples/providers/src/app/app.module.ts
new file mode 100644
index 0000000000..09daaa8c82
--- /dev/null
+++ b/aio/content/examples/providers/src/app/app.module.ts
@@ -0,0 +1,25 @@
+// #docplaster
+// #docregion app-module
+import { BrowserModule } from '@angular/platform-browser';
+import { NgModule } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HttpModule } from '@angular/http';
+
+import { AppComponent } from './app.component';
+// CoreModule provides the UserService.
+import { CoreModule } from './core/core.module';
+
+@NgModule({
+ declarations: [
+ AppComponent
+ ],
+ imports: [
+ BrowserModule,
+ FormsModule,
+ HttpModule,
+ CoreModule
+ ],
+ bootstrap: [AppComponent]
+})
+export class AppModule { }
+// #enddocregion app-module
diff --git a/aio/content/examples/providers/src/app/core/core.module.ts b/aio/content/examples/providers/src/app/core/core.module.ts
new file mode 100644
index 0000000000..ccc0d4f324
--- /dev/null
+++ b/aio/content/examples/providers/src/app/core/core.module.ts
@@ -0,0 +1,16 @@
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { FormsModule } from '@angular/forms';
+
+import { UserService } from './user.service';
+
+
+@NgModule({
+ imports: [
+ CommonModule,
+ FormsModule
+ ],
+ declarations: [],
+ providers: [UserService]
+})
+export class CoreModule { }
diff --git a/aio/content/examples/providers/src/app/core/mock-users.ts b/aio/content/examples/providers/src/app/core/mock-users.ts
new file mode 100644
index 0000000000..4afacacb74
--- /dev/null
+++ b/aio/content/examples/providers/src/app/core/mock-users.ts
@@ -0,0 +1,14 @@
+import { User } from './user';
+
+export const USERS: User[] = [
+ { id: 1, name: 'Maria' },
+ { id: 2, name: 'Alex' },
+ { id: 3, name: 'Chuntao' },
+ { id: 4, name: 'Béatrice' },
+ { id: 5, name: 'Sarah' },
+ { id: 6, name: 'Andrés' },
+ { id: 7, name: 'Abdul' },
+ { id: 8, name: 'Pierre' },
+ { id: 9, name: 'Jiao' },
+ { id: 10, name: 'Seth' }
+];
diff --git a/aio/content/examples/providers/src/app/core/user.service.spec.ts b/aio/content/examples/providers/src/app/core/user.service.spec.ts
new file mode 100644
index 0000000000..02fbc8d952
--- /dev/null
+++ b/aio/content/examples/providers/src/app/core/user.service.spec.ts
@@ -0,0 +1,14 @@
+import { TestBed, inject } from '@angular/core/testing';
+import { UserService } from './user.service';
+
+describe('UserService', () => {
+ beforeEach(() => {
+ TestBed.configureTestingModule({
+ providers: [UserService]
+ });
+ });
+
+ it('should ...', inject([UserService], (service: UserService) => {
+ expect(service).toBeTruthy();
+ }));
+});
diff --git a/aio/content/examples/providers/src/app/core/user.service.ts b/aio/content/examples/providers/src/app/core/user.service.ts
new file mode 100644
index 0000000000..a1376c3199
--- /dev/null
+++ b/aio/content/examples/providers/src/app/core/user.service.ts
@@ -0,0 +1,15 @@
+import { Injectable } from '@angular/core';
+
+import { User } from './user';
+import { USERS } from './mock-users';
+
+@Injectable()
+export class UserService {
+
+ constructor() { }
+
+
+ getUsers(): Promise {
+ return Promise.resolve(USERS);
+ }
+}
diff --git a/aio/content/examples/providers/src/app/core/user.ts b/aio/content/examples/providers/src/app/core/user.ts
new file mode 100644
index 0000000000..1f1b75bb39
--- /dev/null
+++ b/aio/content/examples/providers/src/app/core/user.ts
@@ -0,0 +1,4 @@
+export class User {
+ id: number;
+ name: string;
+}
diff --git a/aio/content/examples/providers/src/index.html b/aio/content/examples/providers/src/index.html
new file mode 100644
index 0000000000..15d46bb0a7
--- /dev/null
+++ b/aio/content/examples/providers/src/index.html
@@ -0,0 +1,14 @@
+
+
+
+
+ Providers
+
+
+
+
+
+
+ Loading...
+
+
diff --git a/aio/content/examples/providers/src/main.ts b/aio/content/examples/providers/src/main.ts
new file mode 100644
index 0000000000..a9ca1caf8c
--- /dev/null
+++ b/aio/content/examples/providers/src/main.ts
@@ -0,0 +1,11 @@
+import { enableProdMode } from '@angular/core';
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app/app.module';
+import { environment } from './environments/environment';
+
+if (environment.production) {
+ enableProdMode();
+}
+
+platformBrowserDynamic().bootstrapModule(AppModule);
diff --git a/aio/content/guide/ajs-quick-reference.md b/aio/content/guide/ajs-quick-reference.md
index 2a345c9b1e..0b8c8bb9eb 100644
--- a/aio/content/guide/ajs-quick-reference.md
+++ b/aio/content/guide/ajs-quick-reference.md
@@ -1076,7 +1076,7 @@ The Angular code is shown using TypeScript.
* `imports`: specifies the list of other modules that this module depends upon
* `declaration`: keeps track of your components, pipes, and directives.
- For more information on modules, see [NgModules](guide/ngmodule).
+ For more information on modules, see [NgModules](guide/ngmodules).
diff --git a/aio/content/guide/aot-compiler.md b/aio/content/guide/aot-compiler.md
index e513e649f5..d72caaffb9 100644
--- a/aio/content/guide/aot-compiler.md
+++ b/aio/content/guide/aot-compiler.md
@@ -578,7 +578,7 @@ function; it can only contain a single `return` statement.
The Angular [`RouterModule`](api/router/RouterModule) exports two macro static methods, `forRoot` and `forChild`, to help declare root and child routes.
Review the [source code](https://github.com/angular/angular/blob/master/packages/router/src/router_module.ts#L139 "RouterModule.forRoot source code")
-for these methods to see how macros can simplify configuration of complex [NgModules](guide/ngmodule).
+for these methods to see how macros can simplify configuration of complex [NgModules](guide/ngmodules).
{@ metadata-rewriting}
### Metadata rewriting
diff --git a/aio/content/guide/architecture.md b/aio/content/guide/architecture.md
index 7b829eb9db..06e0546314 100644
--- a/aio/content/guide/architecture.md
+++ b/aio/content/guide/architecture.md
@@ -34,7 +34,8 @@ You'll learn the details in the pages that follow. For now, focus on the big pic
Angular apps are modular and Angular has its own modularity system called _NgModules_.
NgModules are a big deal.
-This page introduces modules; the [NgModules](guide/ngmodule) page covers them in depth.
+This page introduces modules; the [NgModules](guide/ngmodules) pages
+relating to NgModules covers them in detail.
@@ -139,7 +140,7 @@ Hang in there. The confusion yields to clarity with time and experience.
- Learn more from the [NgModules](guide/ngmodule) page.
+ Learn more from the [NgModules](guide/ngmodules) page.
diff --git a/aio/content/guide/attribute-directives.md b/aio/content/guide/attribute-directives.md
index 05d07bf400..f3ab4d5e54 100644
--- a/aio/content/guide/attribute-directives.md
+++ b/aio/content/guide/attribute-directives.md
@@ -53,7 +53,7 @@ The CLI creates `src/app/highlight.directive.ts`, a corresponding test file (`..
-_Directives_ must be declared in [Angular Modules](guide/ngmodule) in the same manner as _components_.
+_Directives_ must be declared in [Angular Modules](guide/ngmodules) in the same manner as _components_.
diff --git a/aio/content/guide/bootstrapping.md b/aio/content/guide/bootstrapping.md
index 8eba316bff..9c212ce3b1 100644
--- a/aio/content/guide/bootstrapping.md
+++ b/aio/content/guide/bootstrapping.md
@@ -1,169 +1,181 @@
# Bootstrapping
-An Angular Module (NgModule) class describes how the application parts fit together.
-Every application has at least one Angular Module, the _root_ module
-that you [bootstrap](#main) to launch the application.
-You can call the class anything you want. The conventional name is `AppModule`.
+#### Prerequisites
-The [**Angular CLI**](https://cli.angular.io/) produces a new project with the following minimal `AppModule`.
-You evolve this module as your application grows.
+A basic understanding of the following:
+* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
-
-
+
+An NgModule describes how the application parts fit together.
+Every application has at least one Angular module, the _root_ module
+that you bootstrap to launch the application.
+By convention, it is usually called `AppModule`.
-After the `import` statements, you come to a class adorned with the
-**`@NgModule`** [_decorator_](guide/glossary#decorator '"Decorator" explained').
+If you use the CLI to generate an app, the default `AppModule` is as follows:
+
+```javascript
+/* JavaScript imports */
+import { BrowserModule } from '@angular/platform-browser';
+import { NgModule } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HttpModule } from '@angular/http';
+
+import { AppComponent } from './app.component';
+
+/* the AppModule class with the @NgModule decorator */
+@NgModule({
+ declarations: [
+ AppComponent
+ ],
+ imports: [
+ BrowserModule,
+ FormsModule,
+ HttpModule
+ ],
+ providers: [],
+ bootstrap: [AppComponent]
+})
+export class AppModule { }
+
+```
+
+After the import statements is a class with the
+**`@NgModule`** [decorator](guide/glossary#decorator '"Decorator" explained').
The `@NgModule` decorator identifies `AppModule` as an `NgModule` class.
-`@NgModule` takes a _metadata_ object that tells Angular how to compile and launch the application.
+`@NgModule` takes a metadata object that tells Angular how to compile and launch the application.
-The `@NgModule` properties for the minimal `AppModule` generated by the CLI are as follows:
+* **_declarations_**—this application's lone component.
+* **_imports_**—import `BrowserModule` to have browser specific services such as DOM rendering, sanitization, and location.
+* **_providers_**—the service providers.
+* **_bootstrap_**—the _root_ component that Angular creates and inserts
+into the `index.html` host web page.
-* **[_declarations_](#declarations)** — declares the application components. At the moment, there is only the `AppComponent`.
-
-
-* **[_imports_](#imports)** — the `BrowserModule`, which this and every application must import in order to run the app in a browser.
-
-
-* **[_providers_](#providers)** — there are none to start but you are likely to add some soon.
-
-
-* **[_bootstrap_](#bootstrap-array)** — the _root_ `AppComponent` that Angular creates and inserts into the `index.html` host web page.
-
-The [Angular Modules (NgModules)](guide/ngmodule) guide dives deeply into the details of `@NgModule`.
-All you need to know at the moment is a few basics about these four properties.
+The default CLI application only has one component, `AppComponent`, so it
+is in both the `declarations` and the `bootstrap` arrays.
{@a declarations}
+## The `declarations` array
-### The _declarations_ array
+The module's `declarations` array tells Angular which components belong to that module.
+As you create more components, add them to `declarations`.
-You tell Angular which components belong to the `AppModule` by listing it in the module's `declarations` array.
-As you create more components, you'll add them to `declarations`.
+You must declare every component in exactly one `NgModule` class.
+If you use a component without declaring it, Angular returns an
+error message.
-You must declare _every_ component in an Angular Module class.
-If you use a component without declaring it, you'll see a clear error message in the browser console.
+The `declarations` array only takes declarables. Declarables
+are components, [directives](guide/attribute-directives) and [pipes](guide/pipes).
+All of a module's declarables must be in the `declarations` array.
+Declarables must belong to exactly one module. The compiler emits
+an error if you try to declare the same class in more than one module.
-You'll learn to create two other kinds of classes —
-[directives](guide/attribute-directives) and [pipes](guide/pipes) —
-that you must also add to the `declarations` array.
+These declared classes are visible within the module but invisible
+to components in a different module unless they are exported from
+this module and the other module imports this one.
+
+An example of what goes into a declarations array follows:
+
+```javascript
+ declarations: [
+ YourComponent,
+ YourPipe,
+ YourDirective
+ ],
+```
+
+A declarable can only belong to one module, so only declare it in
+one `@NgModule`. When you need it elsewhere,
+import the module that has the declarable you need in it.
+
+**Only `@NgModule` references** go in the `imports` array.
+
+
+### Using directives with `@NgModule`
+
+Use the `declarations` array for directives.
+To use a directive, component, or pipe in a module, you must do a few things:
+
+1. Export it from the file where you wrote it.
+2. Import it into the appropriate module.
+3. Declare it in the `@NgModule` `declarations` array.
+
+
+Those three steps look like the following. In the file where you create your directive, export it.
+The following example, named `ItemDirective` is the default directive structure that the CLI generates in its own file, `item.directive.ts`:
+
+
+
+
+The key point here is that you have to export it so you can import it elsewhere. Next, import it
+into the NgModule, in this example `app.module.ts`, with a JavaScript import statement:
+
+
+
+
+And in the same file, add it to the `@NgModule` `declarations` array:
+
+
+
+
+
+Now you could use your `ItemDirective` in a component. This example uses `AppModule`, but you'd do it the same way for a feature module. For more about directives, see [Attribute Directives](guide/attribute-directives) and [Structural Directives](guide/structural-directives). You'd also use the same technique for [pipes](guide/pipes) and components.
+
+Remember, components, directives, and pipes belong to one module only. You only need to declare them once in your app because you share them by importing the necessary modules. This saves you time and helps keep your app lean.
-
-**Only _declarables_** — _components_, _directives_ and _pipes_ — belong in the `declarations` array.
-Do not put any other kind of class in `declarations`. Do _not_ declare `NgModule` classes. Do _not_ declare service classes. Do _not_ declare model classes.
-
{@a imports}
-### The _imports_ array
+## The `imports` array
-Angular Modules are a way to consolidate features that belong together into discrete units.
-Many features of Angular itself are organized as Angular Modules.
-HTTP services are in the `HttpClientModule`. The router is in the `RouterModule`.
-Eventually you may create your own modules.
+The module's `imports` array appears exclusively in the `@NgModule` metadata object.
+It tells Angular about other NgModules that this particular module needs to function properly.
-Add a module to the `imports` array when the application requires its features.
-
-_This_ application, like most applications, executes in a browser.
-Every application that executes in a browser needs the `BrowserModule` from `@angular/platform-browser`.
-So every such application includes the `BrowserModule` in its _root_ `AppModule`'s `imports` array.
-Other guide pages will tell you when you need to add additional modules to this array.
-
-
-
-**Only `@NgModule` classes** go in the `imports` array. Do not put any other kind of class in `imports`.
-
-
-
-
-The `import` statements at the top of the file and the NgModule's `imports` array
-are unrelated and have completely different jobs.
-
-The _JavaScript_ `import` statements give you access to symbols _exported_ by other files
-so you can reference them within _this_ file.
-You add `import` statements to almost every application file.
-They have nothing to do with Angular and Angular knows nothing about them.
-
-The _module's_ `imports` array appears _exclusively_ in the `@NgModule` metadata object.
-It tells Angular about specific _other_ Angular Modules—all of them classes decorated
-with `@NgModule`—that the application needs to function properly.
-
-
-
-{@a providers}
-
-### The _providers_ array
-
-Angular apps rely on [_dependency injection (DI)_](guide/dependency-injection)
-to deliver services to various parts of the application.
-
-Before DI can inject a service, it must create that service with the help of a _provider_.
-You can tell DI about a service's _provider_ in a number of ways.
-Among the most popular ways is to register the service in the root `ngModule.providers` array, which will make that service available _everywhere_.
-
-For example, a data service provided in the `AppModule`s _providers_ can be injected into any
-component anywhere in the application.
+This list of modules are those that export components, directives, or pipes
+that the component templates in this module reference. In this case, the component is
+`AppComponent`, which references components, directives, or pipes in `BrowserModule`,
+`FormsModule`, or `HttpModule`.
+A component template can reference another component, directive,
+or pipe when the referenced class is declared in this module or
+the class was imported from another module.
You don't have any services to provide yet.
But you will create some before long and you may chose to provide many of them here.
{@a bootstrap-array}
-### The _bootstrap_ array
+## The `providers` array
-You launch the application by [_bootstrapping_](#main) the root `AppModule`.
-Among other things, the _bootstrapping_ process creates the component(s) listed in the `bootstrap` array
+The providers array is where you list the services the app needs. When
+you list services here, they are available app-wide. You can scope
+them when using feature modules and lazy loading. For more information, see
+[Providers](guide/providers).
+
+## The `bootstrap` array
+
+The application launches by bootstrapping the root `AppModule`, which is
+also referred to as an `entryComponent`.
+Among other things, the bootstrapping process creates the component(s) listed in the `bootstrap` array
and inserts each one into the browser DOM.
Each bootstrapped component is the base of its own tree of components.
-Inserting a bootstrapped component usually triggers a cascade of component creations that fill out that tree.
+Inserting a bootstrapped component usually triggers a cascade of
+component creations that fill out that tree.
-While you can put more than one component tree on a host web page, that's not typical.
-Most applications have only one component tree and they bootstrap a single _root_ component.
+While you can put more than one component tree on a host web page,
+most applications have only one component tree and bootstrap a single root component.
-You can call the one _root_ component anything you want but most developers call it `AppComponent`.
+This one root component is usually called `AppComponent` and is in the
+root module's `bootstrap` array.
-Which brings us to the _bootstrapping_ process itself.
-{@a main}
-
-## Bootstrap in _main.ts_
-
-While there are many ways to bootstrap an application, most applications do so in the `src/main.ts` that is generated by the Angular CLI.
-
-
-
-
-This code creates a browser platform for dynamic compilation and
-bootstraps the `AppModule` described above.
-
-The _bootstrapping_ process sets up the execution environment,
-digs the _root_ `AppComponent` out of the module's `bootstrap` array,
-creates an instance of the component and inserts it within the element tag identified by the component's `selector`.
-
-The `AppComponent` selector — here and in most documentation samples — is `app-root`
-so Angular looks for a `` tag in the `index.html` like this one ...
-
-
-
- <body>
- <app-root></app-root>
- </body>
-
-
-
-... and displays the `AppComponent` there.
-
-The `main.ts` file is very stable. Once you've set it up, you may never change it again.
## More about Angular Modules
-Your initial app has only a single module, the _root_ module.
-As your app grows, you'll consider subdividing it into multiple "feature" modules,
-some of which can be loaded later ("lazy loaded") if and when the user chooses
-to visit those features.
+For more on NgModules you're likely to see frequently in apps,
+see [Frequently Used Modules](#).
-When you're ready to explore these possibilities, visit the [Angular Modules](guide/ngmodule) guide.
diff --git a/aio/content/guide/change-log.md b/aio/content/guide/change-log.md
index 3da78c2096..a1e08a8866 100644
--- a/aio/content/guide/change-log.md
+++ b/aio/content/guide/change-log.md
@@ -181,7 +181,7 @@ The _Routing Module_ replaces the previous _routing object_ involving the `Modul
All guided samples with routing use the _Routing Module_ and prose content has been updated,
most conspicuously in the
-[NgModule](guide/ngmodule) guide and [NgModule FAQ](guide/ngmodule-faq) guide.
+[NgModule](guide/ngmodules) guide and [NgModule FAQ](guide/ngmodule-faq) guide.
## New "Internationalization" guide (2016-09-30)
diff --git a/aio/content/guide/dependency-injection.md b/aio/content/guide/dependency-injection.md
index 61c351cf8d..2170c6e3c8 100644
--- a/aio/content/guide/dependency-injection.md
+++ b/aio/content/guide/dependency-injection.md
@@ -160,7 +160,7 @@ Providing the `UserService` with an Angular module is a good choice.
To be precise, Angular module providers are registered with the root injector
-_unless the module is_ [lazy loaded](guide/ngmodule#lazy-load-DI).
+_unless the module is_ [lazy loaded](guide/lazy-loading-ngmodules).
In this sample, all modules are _eagerly loaded_ when the application starts,
so all module providers are registered with the app's root injector.
diff --git a/aio/content/guide/entry-components.md b/aio/content/guide/entry-components.md
new file mode 100644
index 0000000000..2819f0ffd1
--- /dev/null
+++ b/aio/content/guide/entry-components.md
@@ -0,0 +1,116 @@
+# Entry Components
+
+#### Prerequisites:
+
+A basic understanding of the following concepts:
+* [Bootstrapping](guide/bootstrapping).
+
+
+
+An entry component is any component that Angular loads imperatively, (which means you’re not referencing it in the template), by type. You specify an entry component by bootstrapping it in an NgModule,or including it in a routing definition.
+
+
+
+To contrast the two types of components, there are components which are included in the template, which are declarative. Additionally, there are components which you load imperatively; that is, entry components.
+
+
+
+
+There are two main kinds of entry components:
+
+* The bootstrapped root component.
+* A component you specify in a route definition.
+
+
+## A bootstrapped entry component
+
+
+The following is an example of specifying a bootstrapped component,
+`AppComponent`, in a basic `app.module.ts`:
+
+```javascript
+@NgModule({
+ declarations: [
+ AppComponent
+ ],
+ imports: [
+ BrowserModule,
+ FormsModule,
+ HttpModule,
+ AppRoutingModule
+ ],
+ providers: [],
+ bootstrap: [AppComponent] // bootstrapped entry component
+})
+```
+A bootstrapped component is an entry component
+that Angular loads into the DOM during the bootstrap (application launch), process.
+Other entry components are loaded dynamically by other means, such as with the router.
+
+Angular loads a root `AppComponent` dynamically because it's listed by type in `@NgModule.bootstrap`.
+
+
+
+A component can also be bootstrapped imperatively with the module's `ngDoBootstrap()` method.
+The `@NgModule.bootstrap` property tells the compiler that this is an entry component and
+it should generate code to bootstrap the application with this component.
+
+
+
+
+A bootstrapped component is necessarily an entry component because bootstrapping is an imperative process, thus it needs to have an entry component.
+
+## A routed entry component
+
+
+The second kind of entry component occurs in a route definition like
+this:
+
+```javascript
+const routes: Routes = [
+ {
+ path: '',
+ component: CustomerListComponent
+ }
+];
+```
+
+A route definition refers to a component by its type with `component: CustomerListComponent`.
+
+All router components must be `entryComponents`. Because this would require you to add the component in two places (router and `entryComponent`) the Compiler is smart enough to recognize that this is a router definition and automatically add the router component into `entryComponents`.
+
+
+## The `entryComponents` array
+
+Though the `@NgModule` decorator has an `entryComponents` array, most of the time
+you won't have to explicitly set any entry components because Angular adds components listed in `@NgModule.bootstrap` and those in route definitions to entry components automatically. Though these two mechanisms account for most entry components, if your app happens to bootstrap or dynamically load a component by type imperatively,
+you must add it to `entryComponents` explicitly.
+
+### `entryComponents` and the compiler
+
+For production apps you want to load the smallest code possible.
+The code should contain only the classes that you actually need and
+exclude components that are never used. For this reason, the Angular compiler only generates code for components which are reachable from the `entryComponents`; This means that adding more references to `@NgModule.declarations` does not imply that they will necessarily be included in the final bundle.
+
+In fact, many libraries declare and export components you'll never use.
+For example, a material design library will export all components because it doesn’t know which ones the you will use. However, it is unlikely that the you will use them all.
+For the ones you don't reference, the tree shaker drops these components from the final code package.
+
+If a component isn't an _entry component_ or isn't found in a template,
+The tree shaker will throw it away. So, it's best to add only the components that are truly entry components to help keep your app
+as trim as possible.
+
+
+
+
+## More on Angular modules
+
+You may also be interested in the following:
+* [Types of NgModules](guide/module-types)
+* [Lazy Loading Modules with the Angular Router](guide/lazy-loading-ngmodules).
+* [Providers](guide/providers).
+* [NgModules FAQ](guide/ngmodule-faq).
+
+
+
+
diff --git a/aio/content/guide/feature-modules.md b/aio/content/guide/feature-modules.md
new file mode 100644
index 0000000000..890f0baf27
--- /dev/null
+++ b/aio/content/guide/feature-modules.md
@@ -0,0 +1,134 @@
+# Feature Modules
+
+Feature modules are NgModules for the purpose of organizing code.
+
+#### Prerequisites
+A basic understanding of the following:
+* [Bootstrapping](guide/bootstrapping).
+* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
+* [Frequently Used Modules](guide/frequent-ngmodules).
+
+For the final sample app with a feature module that this page describes,
+see the .
+
+
+
+As your app grows, you can organize code relevant for a specific feature.
+This helps apply clear boundaries for features. With feature modules,
+you can keep code related to a specific functionality or feature
+separate from other code. Delineating areas of your
+app helps with collaboration between developers and teams, separating
+directives, and managing the size of the root module.
+
+
+## Feature modules vs. root modules
+
+A feature module is an organizational best practice, as opposed to a concept of the core Angular API. A feature module delivers a cohesive set of functionality focused on a
+specific application need such as a user workflow, routing, or forms.
+While you can do everything within the root module, feature modules
+help you partition the app into focused areas. A feature module
+collaborates with the root module and with other modules through
+the services it provides and the components, directives, and
+pipes that it shares.
+
+## How to make a feature module
+
+Assuming you already have a CLI generated app, create a feature
+module using the CLI by entering the following command in the
+root project directory. Replace `CustomerDashboard` with the
+name of your module. You can omit the word module because the CLI appends it:
+
+```sh
+ng generate module CustomerDashboard
+
+```
+
+
+This causes the CLI to create a folder called `customer-dashboard` with a file inside called `customer-dashboard.module.ts` with the following contents:
+
+```ts
+
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+@NgModule({
+ imports: [
+ CommonModule
+ ],
+ declarations: []
+})
+
+export class CustomerDashboardModule { }
+
+
+```
+
+The structure of an NgModule is the same whether it is a root module or a feature module. In the CLI generated feature module, there are two JavaScript import statements at the top of the file: the first imports `NgModule`, which, like the root module, lets you use the `@NgModule` decorator; the second imports `CommonModule`, which contributes many common directives such as `ngIf` and `ngFor`. Feature modules import `CommonModule` instead of `BrowserModule`, which is only imported once in the root module. `CommonModule` only contains information for common directives such as `ngIf` and `ngFor` which are needed in most templates, whereas `BrowserModule` configures the Angular app for the browser which needs to be done only once.
+
+The `declarations` array is available for you to add declarables, which
+are components, directives, and pipes that belong exclusively to this particular module. To add a component, enter the following command at the command line where `customer-dashboard` is the directory where the CLI generated the feature module and `CustomerDashboard` is the name of the component:
+
+```sh
+ng generate component customer-dashboard/CustomerDashboard
+
+```
+
+This generates a folder for the new component within the customer-dashboard folder and updates the feature module with the `CustomerDashboardComponent` info:
+
+
+
+
+
+
+
+The `CustomerDashboardComponent` is now in the JavaScript import list at the top and added to the `declarations` array, which lets Angular know to associate this new component with this feature module.
+
+## Importing a feature module
+
+To incorporate the feature module into your app, you have to let the root module, `app.module.ts`, know about it. Notice the `CustomerDashboardModule` export at the bottom of `customer-dashboard.module.ts`. This exposes it so that other modules can get to it. To import it into the AppModule, add it to the imports in `app.module.ts` and to the imports array:
+
+
+
+
+
+Now the `AppModule` knows about the feature module. If you were to add any service providers to the feature module, `AppModule` would know about those too, as would any other feature modules. However, NgModules don’t expose their components.
+
+
+## Rendering a feature module’s component template
+
+When the CLI generated the `CustomerDashboardComponent` for the feature module, it included a template, `customer-dashboard.component.html`, with the following markup:
+
+
+
+
+
+To see this HTML in the `AppComponent`, you first have to export the `CustomerDashboardComponent` in the `CustomerDashboardModule`. In `customer-dashboard.module.ts`, just beneath the declarations array, add an exports array containing `CustomerDashboardModule`:
+
+
+
+
+
+
+Next, in the `AppComponent`, `app.component.html`, add the tag ``:
+
+
+
+
+
+Now, in addition to the title that renders by default, the `CustomerDashboardComponent` template renders too:
+
+
+
+
+
+
+
+
+## More on NgModules
+
+You may also be interested in the following:
+* [Lazy Loading Modules with the Angular Router](guide/lazy-loading-ngmodules).
+* [Providers](guide/providers).
+* [Types of NgModules](guide/module-types).
+
+
diff --git a/aio/content/guide/frequent-ngmodules.md b/aio/content/guide/frequent-ngmodules.md
new file mode 100644
index 0000000000..e50bf17bcb
--- /dev/null
+++ b/aio/content/guide/frequent-ngmodules.md
@@ -0,0 +1,138 @@
+# Frequently Used Modules
+
+#### Prerequisites
+
+A basic understanding of [Bootstrapping](guide/bootstrapping).
+
+
+
+
+An Angular app needs at least one module that serves as the root module.
+As you add features to your app, you can add them in modules.
+The following are frequently used Angular modules with examples
+of some of the things they contain:
+
+
+
+
+
+
+ NgModule
+
+
+
+ Import it from
+
+
+
+ Why you use it
+
+
+
+
+
BrowserModule
+
@angular/platform-browser
+
When you want to run your app in a browser
+
+
+
+
CommonModule
+
@angular/common
+
When you want to use NgIf, NgFor
+
+
+
+
FormsModule
+
@angular/forms
+
When you build template driven forms (includes NgModel)
+
+
+
+
ReactiveFormsModule
+
@angular/forms
+
When building reactive forms
+
+
+
+
RouterModule
+
@angular/forms
+
For Routing and when you want to use RouterLink,.forRoot(), and .forChild()
+
+
+
+
HttpModule
+
@angular/http
+
When you to talk to a server
+
+
+
+
+## Importing modules
+
+When you use these Angular modules, import them in `AppModule`,
+or your feature module as appropriate, and list them in the `@NgModule`
+`imports` array. For example, in the basic app generated by the CLI,
+`BrowserModule` is the first import at the top of the `AppModule`,
+`app.module.ts`. Notice that this is the same case for `FormsModule` and `HttpModule`.
+
+
+```javascript
+/* import modules so that AppModule can access them */
+import { BrowserModule } from '@angular/platform-browser';
+import { NgModule } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HttpModule } from '@angular/http';
+
+import { AppComponent } from './app.component';
+
+@NgModule({
+declarations: [
+ AppComponent
+],
+imports: [ /* add modules here so Angular knows to use them */
+ BrowserModule,
+ FormsModule,
+ HttpModule
+],
+providers: [],
+bootstrap: [AppComponent]
+})
+export class AppModule { }
+```
+
+The imports at the top of the array are JavaScript import statements
+while the `imports` array within `@NgModule` is Angular specific.
+For more information on the difference, see [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
+
+
+## `BrowserModule` and `CommonModule`
+
+`BrowserModule` imports `CommonModule`, which contributes many common
+directives such as `ngIf` and `ngFor`. Additionally, `BrowserModule`
+re-exports `CommonModule` making all of its directives available
+to any module that imports `BrowserModule`.
+
+For apps that run in the browser, import `BrowserModule` in the
+root `AppModule` because it provides services that are essential
+to launch and run a browser app. `BrowserModule`’s providers
+are for the whole app so it should only be in the root module,
+not in feature modules. Feature modules only need the common
+directives in `CommonModule`; they don’t need to re-install app-wide providers.
+
+If you do import `BrowserModule` into a lazy loaded feature module,
+Angular returns an error telling you to use `CommonModule` instead.
+
+
+
+
+
+
+
+
+## More on NgModules
+
+You may also be interested in the following:
+* [Bootstrapping](guide/bootstrapping).
+* [NgModules](guide/ngmodules).
+* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
+
diff --git a/aio/content/guide/glossary.md b/aio/content/guide/glossary.md
index 11f82ac237..75d53452c8 100644
--- a/aio/content/guide/glossary.md
+++ b/aio/content/guide/glossary.md
@@ -478,9 +478,11 @@ Read more in the [Lifecycle Hooks](guide/lifecycle-hooks) page.
Angular has the following types of modules:
* [NgModules](guide/glossary#ngmodule).
-For details and examples, see the [NgModules](guide/ngmodule) page.
+For details and examples, see the [NgModules](guide/ngmodules) page.
* ES2015 modules, as described in this section.
+For a comparison, see [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
+
@@ -526,7 +528,8 @@ An NgModule identifies the components, directives, and pipes that the applicatio
Every Angular application has an application root-module class. By convention, the class is
called `AppModule` and resides in a file named `app.module.ts`.
-For details and examples, see [NgModules](guide/ngmodule).
+For details and examples, see [NgModules](guide/ngmodules) and the
+related files in that section.
diff --git a/aio/content/guide/lazy-loading-ngmodules.md b/aio/content/guide/lazy-loading-ngmodules.md
new file mode 100644
index 0000000000..579bd5f07a
--- /dev/null
+++ b/aio/content/guide/lazy-loading-ngmodules.md
@@ -0,0 +1,230 @@
+# Lazy Loading Feature Modules
+
+#### Prerequisites
+A basic understanding of the following:
+* [Feature Modules](guide/feature-modules).
+* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
+* [Frequently Used Modules](guide/frequent-ngmodules).
+* [Types of Modules](guide/module-types).
+* [Routing and Navigation](guide/router).
+
+For the final sample app with two lazy loaded modules that this page describes, see the .
+
+
+
+## High level view
+
+There are three main steps to setting up a lazy loaded feature module:
+
+1. Create the feature module.
+1. Create the feature module’s routing module.
+1. Configure the routes.
+
+## Set up an app
+
+If you don’t already have an app, you can follow the steps below to
+create one with the CLI. If you do already have an app, skip to
+[Configure the routes](#config-routes). Enter the following command
+where `customer-app` is the name of your app:
+
+```sh
+ng new customer-app --routing
+```
+
+This creates an app called `customer-app` and the `--routing` flag
+generates a file called `app-routing.module.ts`, which is one of
+the files you need for setting up lazy loading for your feature module.
+Navigate into the project by issuing the command `cd customer-app`.
+
+## Create a feature module with routing
+
+Next, you’ll need a feature module to route to. To make one, enter
+the following command at the terminal window prompt where `customers` is the name of the module:
+
+```sh
+ng generate module customers --routing
+```
+
+This creates a customers folder with two files inside; `CustomersModule`
+and `CustomersRoutingModule`. `CustomersModule` will act as the gatekeeper
+for anything that concerns customers. `CustomersRoutingModule` will handle
+any customer-related routing. This keeps the app’s structure organized as
+the app grows and allows you to reuse this module while easily keeping its routing intact.
+
+The CLI imports the `CustomersRoutingModule` into the `CustomersModule` by
+adding a JavaScript import statement at the top of the file and adding
+`CustomersRoutingModule` to the `@NgModule` `imports` array.
+
+## Add a component to the feature module
+
+In order to see the module being lazy loaded in the browser, create a component to render some HTML when the app loads `CustomersModule`. At the command line, enter the following:
+
+```sh
+ng generate component customers/customer-list
+```
+
+This creates a folder inside of `customers` called `customer-list`
+with the four files that make up the component.
+
+
+
+Just like with the routing module, the CLI imports the
+`CustomerListComponent` into the `CustomersModule`.
+
+
+## Add another feature module
+
+For another place to route to, create a second feature module with routing:
+
+```sh
+ng generate module orders --routing
+```
+
+This makes a new folder called `orders` containing an `OrdersModule` and an `OrdersRoutingModule`.
+
+Now, just like with the `CustomersModule`, give it some content:
+
+```sh
+ng generate component orders/order-list
+```
+
+## Set up the UI
+
+Though you can type the URL into the address bar, a nav
+is easier for the user and more common. Replace the default
+placeholder markup in `app.component.html` with a custom nav
+so you can easily navigate to your modules in the browser:
+
+
+
+
+
+
+
+
+To see your app in the browser so far, enter the following command in the terminal window:
+
+```sh
+ng serve
+```
+
+Then go to `localhost:4200` where you should see “app works!” and three buttons.
+
+
+
+
+
+
+To make the buttons work, you need to configure the routing modules.
+
+{@a config-routes}
+
+## Configure the routes
+
+The two feature modules, `OrdersModule` and `CustomersModule`, have to be
+wired up to the `AppRoutingModule` so the router knows about them. The structure is as follows:
+
+
+
+
+
+
+Each feature module acts as a doorway via the router. In the `AppRoutingModule`, you configure the routes to the feature modules, in this case `OrdersModule` and `CustomersModule`. This way, the router knows to go to the feature module. The feature module then connects the `AppRoutingModule` to the `CustomersRoutingModule` or the `OrdersRoutingModule`. Those routing modules tell the router where to go to load relevant components.
+
+### Routes at the app level
+
+In `AppRoutingModule`, update the `routes` array with the following:
+
+
+
+
+
+
+
+The import statements stay the same. The first two paths are the routes to the `CustomersModule` and the `OrdersModule` respectively. Notice that the lazy loading syntax uses `loadChildren` followed by a string that is the path to the module, a hash mark or `#`, and the module’s class name.
+
+### Inside the feature module
+
+Next, take a look at `customers.module.ts`. If you’re using the CLI and following the steps outlined in this page, you don’t have to do anything here. The feature module is like a connector between the `AppRoutingModule` and the feature routing module. The `AppRoutingModule` imports the feature module, `CustomersModule`, and `CustomersModule` in turn imports the `CustomersRoutingModule`.
+
+
+
+
+
+
+
+
+The `customers.module.ts` file imports the `CustomersRoutingModule` and `CustomerListComponent` so the `CustomersModule` class can have access to them. `CustomersRoutingModule` is then listed in the `@NgModule` `imports` array giving `CustomersModule` access to its own routing module, and `CustomerListComponent` is in the `declarations` array, which means `CustomerListComponent` belongs to the `CustomersModule`.
+
+
+### Configure the feature module’s routes
+
+The next step is in `customers-routing.module.ts`. First, import the component at the top of the file with the other JavaScript import statements. Then, add the route to `CustomerListComponent`.
+
+
+
+
+
+
+Notice that the `path` is set to an empty string. This is because the path in `AppRoutingModule` is already set to `customers`, so this route in the `CustomersRoutingModule`, is already within the `customers` context. Every route in this routing module is a child route.
+
+Repeat this last step of importing the `OrdersListComponent` and configuring the Routes array for the `orders-routing.module.ts`:
+
+
+
+
+
+Now, if you view the app in the browser, the three buttons take you to each module.
+
+## Confirm it’s working
+
+You can check to see that a module is indeed being lazy loaded with the Chrome developer tools. In Chrome, open the dev tools by pressing `Cmd+Option+i` on a Mac or `Ctrl+Alt+i` on a PC and go to the Network Tab.
+
+
+
+
+
+
+Click on the Orders or Customers button. If you see a chunk appear, you’ve wired everything up properly and the feature module is being lazy loaded. A chunk should appear for Orders and for Customers but will only appear once for each.
+
+
+
+
+
+
+
+To see it again, or to test after working in the project, clear everything out by clicking the circle with a line through it in the upper left of the Network Tab:
+
+
+
+
+
+
+Then reload with `Cmd+r` or `Ctrl+r`, depending on your platform.
+
+## `forRoot()` and `forChild()`
+
+You might have noticed that the CLI adds `RouterModule.forRoot(routes)` to the `app-routing.module.ts` `imports` array. This lets Angular know that this module,
+`AppRoutingModule`, is a routing module and `forRoot()` specifies that this is the root
+routing module. It configures all the
+routes you pass to it, gives you access to the router directives, and registers the `RouterService`.
+Use `forRoot()` in the `AppRoutingModule`—that is, one time in the app at the root level.
+
+The CLI also adds `RouterModule.forChild(routes)` to feature routing modules. This way, Angular
+knows that the route list is only responsible for providing additional routes and is intended for feature modules. You can use `forChild()` in multiple modules.
+
+`forRoot()` contains injector configuration which is global; such as configuring the Router. `forChild()` has no injector configuration, only directives such as `RouterOutlet` and `RouterLink`.
+
+
+
+
+## More on NgModules and routing
+
+You may also be interested in the following:
+* [Routing and Navigation](guide/router).
+* [Providers](guide/providers).
+* [Types of NgModules](guide/module-types).
+
+
+
diff --git a/aio/content/guide/module-types.md b/aio/content/guide/module-types.md
new file mode 100644
index 0000000000..3276078bca
--- /dev/null
+++ b/aio/content/guide/module-types.md
@@ -0,0 +1,192 @@
+
+
+# Types of Feature Modules
+
+#### Prerequisites
+
+A basic understanding of the following concepts:
+* [Feature Modules](guide/feature-modules).
+* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
+* [Frequently Used Modules](guide/frequent-ngmodules).
+
+
+
+There are five general categories of feature modules which
+tend to fall into the following groups:
+
+* Domain feature modules.
+* Routed feature modules.
+* Routing modules.
+* Service feature modules.
+* Widget feature modules.
+
+While the following guidelines describe the use of each type and their
+typical characteristics, in real world apps, you may see hybrids.
+
+
+
+
+
+ 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.
+
+ They typically have a top component that acts as the feature root and private, supporting sub-components descend from it.
+
+ Domain feature modules consist mostly of declarations. Only the top component is exported.
+
+ 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 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(page forthcoming). 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 `HttpModule` 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.
+
+
+
+
+ Feature Module
+
+
+
+ Declarations
+
+
+
+ Providers
+
+
+
+ Exports
+
+
+
+ Imported by
+
+
+
+
+
Domain
+
Yes
+
Rare
+
Top component
+
Feature, AppModule
+
+
+
+
Routed
+
Yes
+
Rare
+
No
+
None
+
+
+
+
Routing
+
No
+
Yes (Guards)
+
RouterModule
+
Feature (for routing)
+
+
+
+
Service
+
No
+
Yes
+
No
+
AppModule
+
+
+
+
Widget
+
Yes
+
Rare
+
Yes
+
Feature
+
+
+
+
+
+## More on NgModules
+
+You may also be interested in the following:
+* [Lazy Loading Modules with the Angular Router](guide/lazy-loading-ngmodules).
+* [Providers](guide/providers).
+* [Types of NgModules](guide/module-types).
diff --git a/aio/content/guide/ngmodule-api.md b/aio/content/guide/ngmodule-api.md
new file mode 100644
index 0000000000..98f244904d
--- /dev/null
+++ b/aio/content/guide/ngmodule-api.md
@@ -0,0 +1,244 @@
+# NgModule API
+
+#### Prerequisites
+
+A basic understanding of the following concepts:
+* [Bootstrapping](guide/bootstrapping).
+* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
+
+
+
+## Purpose of `@NgModule`
+
+At a high level, NgModules are a way to organize Angular apps
+and they accomplish this through the metadata in the `@NgModule`
+decorator. The metadata falls
+into three categories:
+
+* **Static:** Compiler configuration which tells the compiler about directive selectors and where in templates the directives should be applied through selector matching. This is configured via the `declarations` array.
+* **Runtime:** Injector configuration via the `providers` array.
+* **Composability/Grouping:** Bringing NgModules together and making them available via the `imports` and `exports` arrays.
+
+```ts
+@NgModule({
+ // Static, that is compiler configuration
+ declarations: [], // Configure the selectors
+ entryComponents: [], // Generate the host factory
+
+ // Runtime, or injector configuration
+ providers: [], // Runtime injector configuration
+
+ // Composability / Grouping
+ imports: [], // composing NgModules together
+ exports: [] // making NgModules available to other parts of the app
+})
+```
+
+## `@NgModule` metadata
+
+The following table summarizes the `NgModule` metadata properties.
+
+
+
+
+
+
+ Property
+
+
+
+ Description
+
+
+
+
+
+
+
+ declarations
+
+
+
+
+
+ A list of [declarable](guide/ngmodule-faq#q-declarable) classes,
+ (*components*, *directives*, and *pipes*) that _belong to this module_.
+
+1) When compiling a template, you need to determine a set of selectors which should be used for triggering their corresponding directives.
+2) The template is compiled within a context of an `NgModule`—the `NgModule` which this template's component is declared in—which determines the set of selectors using the following rules:
+ a) All selectors of directives listed in `declarations`
+ b) All exported selectors of imported `NgModules`.
+
+
+ Components, directives, and pipes must belong to _exactly_ one module.
+ The compiler emits an error if you try to declare the same class in more than one module.
+
+ Don't re-declare a class imported from another module.
+
+
+
+
+
+
+
+
+ providers
+
+
+
+
+
+ A list of dependency-injection providers.
+
+ Angular registers these providers with the NgModule's injector.
+ If it is the NgModule used for bootstrapping that it is the root injector.
+
+ These services become available for injection into any component, directive, pipe or service which is a child of this injector.
+
+ A lazy-loaded module has its own injector which
+ is typically a child of the application root injector.
+
+ Lazy-loaded services are scoped to the lazy module's injector.
+ If a lazy-loaded module also provides the `UserService`,
+ any component created within that module's context (such as by router navigation)
+ gets the local instance of the service, not the instance in the root application injector.
+
+ Components in external modules continue to receive the instance provided by their injectors.
+
+ For more information on injector hierarchy and scoping, see [Providers](guide/providers).
+
+
+
+
+
+
+
+
+ imports
+
+
+
+
+
+ A list of modules which should be folded into this module. Folded means it is
+ as if all of the imported NgModule properties were declared here.
+
+ Specifically, it is as if the list of modules whose exported components, directives, or pipes
+ are referenced by the component templates were declared in this module.
+
+ A component template can [reference](guide/ngmodule-faq#q-template-reference) another component, directive, or pipe
+ when the reference is declared in this module
+ or if the imported module has exported it.
+ For example, a component can use the `NgIf` and `NgFor` directives only if the
+ module has imported the Angular `CommonModule` (perhaps indirectly by importing `BrowserModule`).
+
+ You can import many standard directives from the `CommonModule`
+ but some familiar directives belong to other modules.
+ For example, you can use `[(ngModel)]` only
+ after importing the Angular `FormsModule`.
+
+
+
+
+
+
+
+ exports
+
+
+
+
+
+ A list of declarations—*component*, *directive*, and *pipe* classes—that
+ an importing module can use.
+
+ Exported declarations are the module's _public API_.
+ A component in another module can [use](guide/ngmodule-faq#q-template-reference) _this_ module's `UserComponent`
+ if it imports this module and this module exports `UserComponent`.
+
+ Declarations are private by default.
+ If this module does _not_ export `UserComponent`, than only the components within where the `UserComponent` has been declared can use `UserComponent.
+
+ Importing a module does _not_ automatically re-export the imported module's imports.
+ Module 'B' can't use `ngIf` just because it imported module `A` which imported `CommonModule`.
+ Module 'B' must import `CommonModule` itself.
+
+ A module can list another module among its `exports`, in which case
+ all of that module's public components, directives, and pipes are exported.
+
+ [Re-export](guide/ngmodule-faq#q-reexport) makes module transitivity explicit.
+ If Module 'A' re-exports `CommonModule` and Module 'B' imports Module 'A',
+ Module 'B' components can use `ngIf` even though 'B' itself didn't import `CommonModule`.
+
+
+
+
+
+
+
+
+ bootstrap
+
+
+
+
+
+ A list of components that are automatically bootstrapped.
+
+ Usually there's only one component in this list, the _root component_ of the application.
+
+ Angular can launch with multiple bootstrap components,
+ each with its own location in the host web page.
+
+ A bootstrap component is automatically added to `entryComponents`.
+
+
+
+
+
+
+
+
+ entryComponents
+
+
+
+
+
+ A list of components that can be dynamically loaded into the view.
+
+ By default, an Angular app always has at least one entry component, the root component, `AppComponent`. Its purpose is to serve as a point of entry into the app, that is, you bootstrap it to launch the app.
+
+ Routed components are also _entry components_ because they need to be loaded dynamically.
+ The router creates them and drops them into the DOM near a ``.
+
+ While the bootstrapped and routed components are _entry components_,
+ you don't have to add them to a module's `entryComponents` list,
+ as they are added implicitly.
+
+ Angular automatically adds components in the module's `bootstrap` and route definitions into the `entryComponents` list.
+
+That leaves only components bootstrapped using one of the imperative techniques, such as [`ViewComponentRef.createComponent()`](https://angular.io/api/core/ViewContainerRef#createComponent) as undiscoverable.
+
+ Dynamic component loading is not common in most apps beyond the router. If you need to dynamically load components, you must add these components to the `entryComponents` list yourself.
+
+ For more information, see [Entry Components](guide/entry-components).
+
+
+
+
+
+
+
+
+
+## More on NgModules
+
+You may also be interested in the following:
+* [Feature Modules](guide/feature-modules).
+* [Entry Components](guide/entry-components).
+* [Providers](guide/providers).
+* [Types of NgModules](guide/module-types).
+
+
+
diff --git a/aio/content/guide/ngmodule-faq.md b/aio/content/guide/ngmodule-faq.md
index 812372e82d..2f8409c561 100644
--- a/aio/content/guide/ngmodule-faq.md
+++ b/aio/content/guide/ngmodule-faq.md
@@ -1,26 +1,24 @@
# NgModule FAQs
-**NgModules** help organize an application into cohesive blocks of functionality.
-The [NgModules](guide/ngmodule) guide takes you step-by-step
-from the most elementary `@NgModule` class to a multi-faceted sample with lazy-loaded modules.
+#### Prerequisites:
+
+A basic understanding of the following concepts:
+* [NgModules](guide/ngmodules).
+
+
+
+NgModules help organize an application into cohesive blocks of functionality.
This page answers the questions many developers ask about NgModule design and implementation.
-
-These FAQs assume that you have read the [NgModules](guide/ngmodule) guide.
+## What classes should I add to the `declarations` array?
-
+Add [declarable](guide/bootstrapping#the-declarations-array) classes—components, directives, and pipes—to a `declarations` list.
-{@a q-what-to-declare}
-
-## What classes should I add to _declarations_?
-
-Add [declarable](guide/ngmodule-faq#q-declarable) classes—components, directives, and pipes—to a `declarations` list.
-
-Declare these classes in _exactly one_ NgModule.
-Declare them in _this_ NgModule if they _belong_ to this module.
+Declare these classes in _exactly one_ module of the application.
+Declare them in a module if they belong to that particular module.
@@ -29,49 +27,45 @@ Declare them in _this_ NgModule if they _belong_ to this module.
## What is a _declarable_?
Declarables are the class types—components, directives, and pipes—that
-you can add to an NgModule's `declarations` list.
-They're the _only_ classes that you can add to `declarations`.
+you can add to a module's `declarations` list.
+They're the only classes that you can add to `declarations`.
-{@a q-what-not-to-declare}
+## What classes should I _not_ add to `declarations`?
-## What classes should I _not_ add to _declarations_?
-
-Add only [declarable](guide/ngmodule-faq#q-declarable) classes to an NgModule's `declarations` list.
+Add only [declarable](guide/bootstrapping#the-declarations-array) classes to an NgModule's `declarations` list.
Do *not* declare the following:
-* A class that's already declared in another NgModule.
-* An array of directives imported from another NgModule.
-For example, don't declare FORMS_DIRECTIVES from `@angular/forms`.
-* NgModule classes.
+* A class that's already declared in another module, whether an app module, @NgModule, or third-party module.
+* An array of directives imported from another module.
+For example, don't declare `FORMS_DIRECTIVES` from `@angular/forms` because the `FormsModule` already declares it.
+
+* Module classes.
* Service classes.
* Non-Angular classes and objects, such as
strings, numbers, functions, entity models, configurations, business logic, and helper classes.
-{@a q-why-multiple-mentions}
-## Why list the same component in multiple _@NgModule_ properties?
+## Why list the same component in multiple `NgModule` properties?
`AppComponent` is often listed in both `declarations` and `bootstrap`.
-You might see `HeroComponent` listed in `declarations`, `exports`, and `entryComponents`.
+You might see the same component listed in `declarations`, `exports`, and `entryComponents`.
While that seems redundant, these properties have different functions.
Membership in one list doesn't imply membership in another list.
* `AppComponent` could be declared in this module but not bootstrapped.
* `AppComponent` could be bootstrapped in this module but declared in a different feature module.
-* `HeroComponent` could be imported from another application module (so you can't declare it) and re-exported by this module.
-* `HeroComponent` could be exported for inclusion in an external component's template
+* A component could be imported from another app module (so you can't declare it) and re-exported by this module.
+* A component could be exported for inclusion in an external component's template
as well as dynamically loaded in a pop-up dialog.
-{@a q-why-cant-bind-to}
-
## What does "Can't bind to 'x' since it isn't a known property of 'y'" mean?
This error often means that you haven't declared the directive "x"
@@ -79,22 +73,16 @@ or haven't imported the NgModule to which "x" belongs.
-You also get this error if "x" really isn't a property or if "x" is a private component property (i.e., lacks the `@Input` or `@Output` decorator).
+Perhaps you declared "x" in an application sub-module but forgot to export it.
+The "x" class isn't visible to other modules until you add it to the `exports` list.
-For example, if "x" is `ngModel`, you may not have imported the `FormsModule` from `@angular/forms`.
-
-Perhaps you declared "x" in an application feature module but forgot to export it?
-The "x" class isn't visible to other components of other NgModules until you add it to the `exports` list.
-
-{@a q-what-to-import}
-
## What should I import?
-Import NgModules whose public (exported) [declarable classes](guide/ngmodule-faq#q-declarable)
+Import NgModules whose public (exported) [declarable classes](guide/bootstrapping#the-declarations-array)
you need to reference in this module's component templates.
This always means importing `CommonModule` from `@angular/common` for access to
@@ -113,9 +101,9 @@ Import only [BrowserModule](guide/ngmodule-faq#q-browser-vs-common-module) in th
{@a q-browser-vs-common-module}
-## Should I import _BrowserModule_ or _CommonModule_?
+## Should I import `BrowserModule` or `CommonModule`?
-The *root application module* (`AppModule`) of almost every browser application
+The root application module, `AppModule`, of almost every browser application
should import `BrowserModule` from `@angular/platform-browser`.
`BrowserModule` provides services that are essential to launch and run a browser app.
@@ -124,25 +112,19 @@ should import `BrowserModule` from `@angular/platform-browser`.
which means that components in the `AppModule` module also have access to
the Angular directives every app needs, such as `NgIf` and `NgFor`.
-_Do not import_ `BrowserModule` in any other NgModule.
+Do not import `BrowserModule` in any other module.
*Feature modules* and *lazy-loaded modules* should import `CommonModule` instead.
They need the common directives. They don't need to re-install the app-wide providers.
-
-
-`BrowserModule` throws an error if you try to lazy load a module that imports it.
-
-
-
Importing `CommonModule` also frees feature modules for use on _any_ target platform, not just browsers.
-{@a q-reimport}
+
-## What if I import the same NgModule twice?
+## What if I import the same module twice?
-That's not a problem. When three NgModules all import Module 'A',
+That's not a problem. When three modules all import Module 'A',
Angular evaluates Module 'A' once, the first time it encounters it, and doesn't do so again.
That's true at whatever level `A` appears in a hierarchy of imported NgModules.
@@ -154,11 +136,11 @@ Angular doesn't like NgModules with circular references, so don't let Module 'A'
-{@a q-what-to-export}
+
## What should I export?
-Export [declarable](guide/ngmodule-faq#q-declarable) classes that components in _other_ NgModules
+Export [declarable](guide/bootstrapping#the-declarations-array) classes that components in _other_ NgModules
are able to reference in their templates. These are your _public_ classes.
If you don't export a class, it stays _private_, visible only to other component
declared in this NgModule.
@@ -171,8 +153,6 @@ An NgModule can even export a module that it doesn't import.
-{@a q-what-not-to-export}
-
## What should I *not* export?
Don't export the following:
@@ -189,10 +169,9 @@ It's only purpose is to add http service providers to the application as a whole
-{@a q-reexport}
-{@a q-re-export}
-## Can I re-export classes and NgModules?
+
+## Can I re-export classes and modules?
Absolutely.
@@ -202,70 +181,63 @@ re-export them in a consolidated, convenience module.
An NgModule can re-export entire NgModules, which effectively re-exports all of their exported classes.
Angular's own `BrowserModule` exports a couple of NgModules like this:
-
+```typescript
exports: [CommonModule, ApplicationModule]
-
+
+```
An NgModule can export a combination of its own declarations, selected imported classes, and imported NgModules.
-
-
Don't bother re-exporting pure service modules.
-Pure service modules don't export [declarable](guide/ngmodule-faq#q-declarable) classes that another NgModule could use.
+Pure service modules don't export [declarable](guide/bootstrapping#the-declarations-array) classes that another NgModule could use.
For example, there's no point in re-exporting `HttpModule` because it doesn't export anything.
It's only purpose is to add http service providers to the application as a whole.
-
-{@a q-for-root}
-## What is the _forRoot_ method?
+## What is the `forRoot()` method?
-The `forRoot` static method is a convention that makes it easy for developers to configure the module's providers.
+The `forRoot()` static method is a convention that makes it easy for developers to configure the module's providers.
-The `RouterModule.forRoot` method is a good example.
-Apps pass a `Routes` object to `RouterModule.forRoot` in order to configure the app-wide `Router` service with routes.
-`RouterModule.forRoot` returns a [ModuleWithProviders](api/core/ModuleWithProviders).
+The `RouterModule.forRoot()` method is a good example.
+Apps pass a `Routes` object to `RouterModule.forRoot()` in order to configure the app-wide `Router` service with routes.
+`RouterModule.forRoot()` returns a [ModuleWithProviders](api/core/ModuleWithProviders).
You add that result to the `imports` list of the root `AppModule`.
-
-
-Only call and import a `.forRoot` result in the root application NgModule, `AppModule`.
-Importing it in any other NgModule, particularly in a lazy-loaded NgModule,
+Only call and import a `.forRoot()` result in the root application module, `AppModule`.
+Importing it in any other module, particularly in a lazy-loaded module,
is contrary to the intent and will likely produce a runtime error.
-
-
`RouterModule` also offers a `forChild` static method for configuring the routes of lazy-loaded modules.
-_forRoot_ and _forChild_ are conventional names for methods that
+`forRoot()` and `forChild()` are conventional names for methods that
configure services in root and feature modules respectively.
Angular doesn't recognize these names but Angular developers do.
Follow this convention when you write similar modules with configurable service providers.
+
-{@a q-module-provider-visibility}
## Why is a service provided in a feature module visible everywhere?
-Providers listed in the `@NgModule.providers` of a bootstrapped module have *application scope*.
+Providers listed in the `@NgModule.providers` of a bootstrapped module have application scope.
Adding a service provider to `@NgModule.providers` effectively publishes the service to the entire application.
When you import an NgModule,
Angular adds the module's service providers (the contents of its `providers` list)
-to the application _root injector_.
+to the application root injector.
-This makes the provider visible to every class in the application that knows the provider's lookup token.
+This makes the provider visible to every class in the application that knows the provider's lookup token, or knows its name.
This is by design.
Extensibility through NgModule imports is a primary goal of the NgModule system.
Merging NgModule providers into the application injector
makes it easy for a module library to enrich the entire application with new services.
-By adding the `HttpModule` once, every application component can make http requests.
+By adding the `HttpModule` once, every application component can make HTTP requests.
However, this might feel like an unwelcome surprise if you expect the module's services
to be visible only to the components declared by that feature module.
@@ -275,11 +247,13 @@ not just the classes declared in the `HeroModule`.
-{@a q-lazy-loaded-module-provider-visibility}
+
+{@ q-lazy-loaded-module-provider-visibility}
-## Why is a service provided in a _lazy-loaded_ NgModule visible only to that module?
-Unlike providers of the NgModules loaded at launch,
+## Why is a service provided in a lazy-loaded module visible only to that module?
+
+Unlike providers of the modules loaded at launch,
providers of lazy-loaded modules are *module-scoped*.
When the Angular router lazy-loads a module, it creates a new execution context.
@@ -294,11 +268,10 @@ Angular prefers service instances created from these providers to the service in
-{@a q-module-provider-duplicates}
-## What if two NgModules provide the same service?
+## What if two modules provide the same service?
-When two imported NgModules, loaded at the same time, list a provider with the same token,
+When two imported modules, loaded at the same time, list a provider with the same token,
the second module's provider "wins". That's because both providers are added to the same injector.
When Angular looks to inject a service for that token,
@@ -315,26 +288,21 @@ The `AppModule` always wins.
-{@a q-component-scoped-providers}
-## How do I restrict service scope to an NgModule?
+## How do I restrict service scope to a module?
-When an NgModule is loaded at application launch,
+When a module is loaded at application launch,
its `@NgModule.providers` have *application-wide scope*;
that is, they are available for injection throughout the application.
Imported providers are easily replaced by providers from another imported NgModule.
Such replacement might be by design. It could be unintentional and have adverse consequences.
-
-
-As a general rule, import NgModules with providers _exactly once_, preferably in the application's _root module_.
+As a general rule, import modules with providers _exactly once_, preferably in the application's _root module_.
That's also usually the best place to configure, wrap, and override them.
-
-
-Suppose an NgModule requires a customized `HttpBackend` that adds a special header for all Http requests.
-If another NgModule elsewhere in the application also customizes `HttpBackend`
+Suppose a module requires a customized `HttpBackend` that adds a special header for all Http requests.
+If another module elsewhere in the application also customizes `HttpBackend`
or merely imports the `HttpModule`, it could override this module's `HttpBackend` provider,
losing the special header. The server will reject http requests from this module.
@@ -359,7 +327,7 @@ with the component's own providers.
When a child of this component asks for the `HttpBackend` service,
Angular provides the local `HttpBackend` service,
not the version provided in the application root injector.
-Child components make proper HTTP requests no matter what other NgModules do to `HttpBackend`.
+Child components make proper HTTP requests no matter what other modules do to `HttpBackend`.
Be sure to create module components as children of this module's top component.
@@ -369,9 +337,10 @@ Define child routes and let the router load module components into that outlet.
-{@a q-root-component-or-module}
+
+{@ q-root-component-or-module}
-## Should I add application-wide providers to the root _AppModule_ or the root _AppComponent_?
+## Should I add application-wide providers to the root `AppModule` or the root `AppComponent`?
Register application-wide providers in the root `AppModule`, not in the `AppComponent`.
@@ -385,87 +354,79 @@ More generally, [prefer registering providers in NgModules](guide/ngmodule-faq#q
Discussion
-Angular registers all startup NgModule providers with the application root injector.
-The services created from root injector providers are available to the entire application.
-They are _application-scoped_.
+Angular registers all startup module providers with the application root injector.
+The services that root injector providers create have application scope, which
+means they are available to the entire application.
-Certain services (such as the `Router`) only work when registered in the application root injector.
+Certain services, such as the `Router`, only work when you register them in the application root injector.
By contrast, Angular registers `AppComponent` providers with the `AppComponent`'s own injector.
`AppComponent` services are available only to that component and its component tree.
-They are _component-scoped_.
+They have component scope.
-The `AppComponent`'s injector is a _child_ of the root injector, one down in the injector hierarchy.
-For applications that don't use the router, that's _almost_ the entire application.
-But for routed applications, "almost" isn't good enough.
+The `AppComponent`'s injector is a child of the root injector, one down in the injector hierarchy.
+For applications that don't use the router, that's almost the entire application.
+But in routed applications, routing operates at the root level
+where `AppComponent` services don't exist.
+This means that lazy-loaded modules can't reach them.
-`AppComponent` services don't exist at the root level where routing operates.
-Lazy-loaded modules can't reach them.
-In the [_NgModules_ sample application](guide/ngmodule), if you had registered `UserService` in the `AppComponent`,
-the `HeroComponent` couldn't inject it.
-The application would fail the moment a user navigated to "Heroes".
+
+{@ q-component-or-module}
-{@a q-component-or-module}
+## Should I add other providers to a module or a component?
-## Should I add other providers to an NgModule or a component?
-
-In general, prefer registering feature-specific providers in NgModules (`@NgModule.providers`)
+In general, prefer registering feature-specific providers in modules (`@NgModule.providers`)
to registering in components (`@Component.providers`).
Register a provider with a component when you _must_ limit the scope of a service instance
to that component and its component tree.
Apply the same reasoning to registering a provider with a directive.
-For example, a hero editing component that needs a private copy of a caching hero service should register
-the `HeroService` with the `HeroEditorComponent`.
-Then each new instance of the `HeroEditorComponent` gets its own cached service instance.
-The changes that editor makes to heroes in its service don't touch the hero instances elsewhere in the application.
+For example, an editing component that needs a private copy of a caching service should register
+the service with the component.
+Then each new instance of the component gets its own cached service instance.
+The changes that editor makes in its service don't touch the instances elsewhere in the application.
[Always register _application-wide_ services with the root `AppModule`](guide/ngmodule-faq#q-root-component-or-module),
not the root `AppComponent`.
-{@a q-why-bad}
+
+{@ q-why-bad}
-## Why is it bad if _SharedModule_ provides a service to a lazy-loaded NgModule?
+## Why is it bad if a shared module provides a service to a lazy-loaded module?
-This question is addressed in the [Why UserService isn't shared](guide/ngmodule#no-shared-module-providers)
-section of the [NgModules](guide/ngmodule) guide,
-which discusses the importance of keeping providers out of the `SharedModule`.
+### The eagerly loaded scenario
+When an eagerly loaded module provides a service, for example a `UserService`, that service is available application-wide. If the root module provides `UserService` and
+imports another module that provides the same `UserService`, Angular registers one of
+them in the root app injector (see [What if I import the same module twice?](guide/ngmodule-faq#q-reimport)).
-Suppose the `UserService` was listed in the NgModule's `providers` (which it isn't).
-Suppose every NgModule imports this `SharedModule` (which they all do).
+Then, when some component injects `UserService`, Angular finds it in the app root injector,
+and delivers the app-wide singleton service. No problem.
-When the app starts, Angular eagerly loads the `AppModule` and the `ContactModule`.
+### The lazy loaded scenario
-Both instances of the imported `SharedModule` would provide the `UserService`.
-Angular registers one of them in the root app injector (see [What if I import the same NgModule twice?](guide/ngmodule-faq#q-reimport)).
-Then some component injects `UserService`, Angular finds it in the app root injector,
-and delivers the app-wide singleton `UserService`. No problem.
+Now consider a lazy loaded module that also provides a service called `UserService`.
-Now consider the `HeroModule` _which is lazy-loaded_.
-
-When the router lazy loads the `HeroModule`, it creates a child injector and registers the `UserService`
+When the router lazy loads a module, it creates a child injector and registers the `UserService`
provider with that child injector. The child injector is _not_ the root injector.
-When Angular creates a lazy `HeroComponent`, it must inject a `UserService`.
-This time it finds a `UserService` provider in the lazy module's _child injector_
+When Angular creates a lazy component for that module and injects `UserService`,
+it finds a `UserService` provider in the lazy module's _child injector_
and creates a _new_ instance of the `UserService`.
This is an entirely different `UserService` instance
than the app-wide singleton version that Angular injected in one of the eagerly loaded components.
-That's almost certainly a mistake.
-
-
-
+This scenario causes your app to create a new instance every time, instead of using the singleton.
+
@@ -508,56 +469,40 @@ To prevent this issue, write a constructor that attempts to inject the module or
from the root app injector. If the injection succeeds, the class has been loaded a second time.
You can throw an error or take other remedial action.
-Certain NgModules (such as `BrowserModule`) implement such a guard,
-such as this `CoreModule` constructor.
+Certain NgModules, such as `BrowserModule`, implement such a guard.
+Here is a custom constructor for an NgModule called `CoreModule`.
-
+
-{@a q-entry-component-defined}
+{@a q-entry-component-defined}
-## What is an _entry component_?
+## What is an `entry component`?
An entry component is any component that Angular loads _imperatively_ by type.
A component loaded _declaratively_ via its selector is _not_ an entry component.
-Most application components are loaded declaratively.
+Most application components are loaded declaratively, which means
Angular uses the component's selector to locate the element in the template.
-It then creates the HTML representation of the component and inserts it into the DOM at the selected element.
-These aren't entry components.
-
-A few components are only loaded dynamically and are _never_ referenced in a component template.
+It then creates the HTML representation of the component and inserts it into the DOM at the selected element. These aren't entry components.
The bootstrapped root `AppComponent` is an _entry component_.
True, its selector matches an element tag in `index.html`.
But `index.html` isn't a component template and the `AppComponent`
selector doesn't match an element in any component template.
-Angular loads `AppComponent` dynamically because it's either listed _by type_ in `@NgModule.bootstrap`
-or bootstrapped imperatively with the NgModule's `ngDoBootstrap` method.
-
Components in route definitions are also _entry components_.
A route definition refers to a component by its _type_.
-The router ignores a routed component's selector (if it even has one) and
+The router ignores a routed component's selector, if it even has one, and
loads the component dynamically into a `RouterOutlet`.
-The compiler can't discover these _entry components_ by looking for them in other component templates.
-You must tell it about them by adding them to the `entryComponents` list.
-
-Angular automatically adds the following types of components to the NgModule's `entryComponents`:
-
-* The component in the `@NgModule.bootstrap` list.
-* Components referenced in router configuration.
-
-You don't have to mention these components explicitly, although doing so is harmless.
+For more information, see [Entry Components](guide/entry-components).
-{@a q-bootstrap_vs_entry_component}
-
## What's the difference between a _bootstrap_ component and an _entry component_?
A bootstrapped component _is_ an [entry component](guide/ngmodule-faq#q-entry-component-defined)
@@ -570,9 +515,9 @@ it should generate code to bootstrap the application with this component.
There's no need to list a component in both the `bootstrap` and `entryComponent` lists,
although doing so is harmless.
-
+For more information, see [Entry Components](guide/entry-components).
-{@a q-when-entry-components}
+
## When do I add components to _entryComponents_?
@@ -591,31 +536,27 @@ it's best to add only the components that are truly _entry components_.
Don't include components that [are referenced](guide/ngmodule-faq#q-template-reference)
in the templates of other components.
+For more information, see [Entry Components](guide/entry-components).
+
-{@a q-why-entry-components}
## Why does Angular need _entryComponents_?
-_Entry components_ are also declared.
-Why doesn't the Angular compiler generate code for every component in `@NgModule.declarations`?
-Then you wouldn't need entry components.
-The reason is _tree shaking_. For production apps you want to load the smallest, fastest code possible.
-The code should contain only the classes that you actually need.
+The reason is _tree shaking_. For production apps you want to load the smallest, fastest code possible. The code should contain only the classes that you actually need.
It should exclude a component that's never used, whether or not that component is declared.
In fact, many libraries declare and export components you'll never use.
If you don't reference them, the tree shaker drops these components from the final code package.
-If the [Angular compiler](guide/ngmodule-faq#q-angular-compiler) generated code for every declared component,
-it would defeat the purpose of the tree shaker.
+If the [Angular compiler](guide/ngmodule-faq#q-angular-compiler) generated code for every declared component, it would defeat the purpose of the tree shaker.
Instead, the compiler adopts a recursive strategy that generates code only for the components you use.
The compiler starts with the entry components,
then it generates code for the declared components it [finds](guide/ngmodule-faq#q-template-reference) in an entry component's template,
then for the declared components it discovers in the templates of previously compiled components,
-and so on. At the end of the process, the compiler has generated code for every entry component
+and so on. At the end of the process, the compiler has generated code for every entry component
and every component reachable from an entry component.
If a component isn't an _entry component_ or wasn't found in a template,
@@ -623,540 +564,96 @@ the compiler omits it.
-{@a q-module-recommendations}
-
-## What kinds of NgModules should I have and how should I use them?
+## What kinds of modules should I have and how should I use them?
Every app is different. Developers have various levels of experience and comfort with the available choices.
-The following suggestions and guidelines have wide appeal.
+Some suggestions and guidelines appear to have wide appeal.
-### _SharedModule_
-
-Create a `SharedModule` with the components, directives, and pipes that you use
-everywhere in your app. This NgModule should consist entirely of `declarations`,
+### `SharedModule`
+`SharedModule` is a conventional name for an `NgModule` with the components, directives, and pipes that you use
+everywhere in your app. This module should consist entirely of `declarations`,
most of them exported.
-The `SharedModule` may re-export other [widget modules](guide/ngmodule-faq#widget-feature-module), such as `CommonModule`,
+The `SharedModule` may re-export other widget modules, such as `CommonModule`,
`FormsModule`, and NgModules with the UI controls that you use most widely.
-The `SharedModule` should *not* have `providers` for reasons [explained previously](guide/ngmodule-faq#q-why-bad).
-Nor should any of its imported or re-exported NgModules have `providers`.
-If you deviate from this guideline, know what you're doing and why.
+The `SharedModule` should not have `providers` for reasons [explained previously](guide/ngmodule-faq#q-why-bad).
+Nor should any of its imported or re-exported modules have `providers`.
Import the `SharedModule` in your _feature_ modules,
both those loaded when the app starts and those you lazy load later.
-### _CoreModule_
-
-Create a `CoreModule` with `providers` for the singleton services you load when the application starts.
+### `CoreModule`
+`CoreModule` is a conventional name for an `NgModule` with `providers` for
+the singleton services you load when the application starts.
Import `CoreModule` in the root `AppModule` only.
Never import `CoreModule` in any other module.
-Consider making `CoreModule` a [pure services module](guide/ngmodule-faq#service-feature-module) with no `declarations`.
+Consider making `CoreModule` a pure services module
+with no `declarations`.
-
-
-This page sample departs from that advice by declaring and exporting two components that are
-only used within the root `AppComponent` declared by `AppModule`.
-Someone following this guideline strictly would have declared these components in the `AppModule` instead.
-
-
+For more information, see [Sharing NgModules](guide/sharing-ngmodules)
+and [Singleton Services](guide/singleton-services).
### Feature Modules
-Create feature modules around specific application business domains, user workflows, and utility collections.
+Feature modules are modules you create around specific application business domains, user workflows, and utility collections. They support your app by containing a particular feature,
+such as routes, services, widgets, etc. To conceptualize what a feature module might be in your
+app, consider that if you would put the files related to a certain functionality, like a search,
+in one folder, that the contents of that folder would be a feature module that you might call
+your `SearchModule`. It would contain all of the components, routing, and templates that
+would make up the search functionality.
-Feature modules tend to fall into one of the following groups:
+For more information, see [Feature Modules](guide/feature-modules) and
+[Module Types](guide/module-types)
- * [Domain feature modules](guide/ngmodule-faq#domain-feature-module).
- * [Routed feature modules](guide/ngmodule-faq#routed-feature-module).
- * [Routing modules](guide/ngmodule-faq#routing-module).
- * [Service feature modules](guide/ngmodule-faq#service-feature-module).
- * [Widget feature modules](guide/ngmodule-faq#widget-feature-module).
-
+## What's the difference between NgModules and JavaScript Modules?
-Real-world NgModules are often hybrids that purposefully deviate from the following guidelines.
-These guidelines are not laws;
-follow them unless you have a good reason to do otherwise.
+In an Angular app, NgModules and JavaScript modules work together.
-
-
-
-
-
-
- Feature Module
-
-
-
- Guidelines
-
-
-
-
-
-
-
- {@a domain-feature-module}Domain
-
-
-
-
- Domain feature modules deliver a user experience *dedicated to a particular application domain*
- like editing a customer or placing an order.
-
- They typically have a top component that acts as the feature root.
- Private, supporting sub-components descend from it.
-
- Domain feature modules consist mostly of _declarations_.
- Only the top component is exported.
-
- 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.
-
- Don't provide application-wide singleton services in a domain feature module.
-
- 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.
-
-
-
-
- For an example, see the [Feature Modules](guide/ngmodule#contact-module-v1)
- section of the [NgModules](guide/ngmodule) guide, before routing is introduced.
-
-
-
-
-
-
-
-
-
-
-
- {@a routed-feature-module}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.
-
- This page's `ContactModule`, `HeroModule`, and `CrisisModule` are routed feature modules.
-
- Routed feature modules _shouldn't export anything_.
- They don't have to because their components never appear in the template of an external component.
-
- A lazy-loaded routed feature module should _not be imported_ by any NgModule.
- Doing so would trigger an eager load, defeating the purpose of lazy loading.
- `HeroModule` and `CrisisModule` are lazy-loaded. They aren't mentioned among the `AppModule` imports.
-
- But an eagerly loaded, routed feature module must be imported by another NgModule
- so that the compiler learns about its components.
- `ContactModule` is eager loaded and therefore listed among the `AppModule` imports.
-
- Routed Feature Modules rarely have _providers_ for reasons [explained earlier](guide/ngmodule-faq#q-why-bad).
- When they do, the lifetime of the provided services
- should be the same as the lifetime of the NgModule.
-
- Don't provide application-wide singleton services in a routed feature module
- or in an NgModule that the routed module imports.
-
-
-
-
-
-
-
- {@a routing-module}Routing
-
-
-
-
-
- A [routing module](guide/router#routing-module) *provides routing configuration* for another NgModule.
-
- A routing module separates routing concerns from its companion module.
-
- A routing module typically does the following:
-
- * Defines routes.
- * Adds router configuration to the module's `imports`.
- * Re-exports `RouterModule`.
- * 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 *should 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.
-
- The `AppRoutingModule`, `ContactRoutingModule`, and `HeroRoutingModule` are good examples.
-
-
-
-
-
- See also [Do you need a _Routing Module_?](guide/router#why-routing-module) on the
- [Routing & Navigation](guide/router) page.
-
-
-
-
-
-
-
-
-
-
-
-
- {@a service-feature-module}Service
-
-
-
-
-
- Service modules *provide utility services* such as data access and messaging.
-
- Ideally, they consist entirely of _providers_ and have no _declarations_.
- The `CoreModule` and Angular's `HttpModule` are good examples.
-
- Service Modules should _only_ be imported by the root `AppModule`.
-
- Do *not* import service modules in other feature modules.
- If you deviate from this guideline, know what you're doing and why.
-
-
-
-
-
-
-
- {@a widget-feature-module}Widget
-
-
-
-
-
- A widget module makes *components, directives, and pipes* available to external NgModules.
-
- `CommonModule` and `SharedModule` are widget 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_.
- If you deviate from this guideline, know what you're doing and why.
-
- Import widget modules in any module whose component templates need the widgets.
-
-
-
-
-
-
-
-
-
-The following table summarizes the key characteristics of each _feature module_ group.
-
-
-
-
-
-Real-world NgModules are often hybrids that knowingly deviate from these guidelines.
-
-
-
-
-
-{@a q-ng-vs-js-modules}
-
-## What's the difference between Angular NgModules and JavaScript Modules?
-
-Angular and JavaScript are different yet complementary module systems.
-
-In modern JavaScript, every file is a _module_
+In modern JavaScript, every file is a module
(see the [Modules](http://exploringjs.com/es6/ch_modules.html) page of the Exploring ES6 website).
-Within each file you write an `export` statement to make parts of the module public:
+Within each file you write an `export` statement to make parts of the module public.
-
- export class AppComponent { ... }
-
-
-Then you `import` a part in another module:
-
-
- import { AppComponent } from './app.component';
-
-
-This kind of modularity is a feature of the _JavaScript language_.
-
-An _NgModule_ is a feature of _Angular_ itself.
-
-Angular's `@NgModule` metadata also have `imports` and `exports` and they serve a similar purpose.
+An Angular NgModule is a class with the `@NgModule` decorator—JavaScript modules
+don't have to have the `@NgModule` decorator. Angular's `NgModule` has `imports` and `exports` and they serve a similar purpose.
You _import_ other NgModules so you can use their exported classes in component templates.
You _export_ this NgModule's classes so they can be imported and used by components of _other_ NgModules.
-The NgModule classes differ from JavaScript module class in the following key ways:
-
-* An NgModule bounds [declarable classes](guide/ngmodule-faq#q-declarable) only.
-Declarables are the only classes that matter to the [Angular compiler](guide/ngmodule-faq#q-angular-compiler).
-* Instead of defining all member classes in one giant file (as in a JavaScript module),
- you list the NgModule's classes in the `@NgModule.declarations` list.
-* An NgModule can only export the [declarable classes](guide/ngmodule-faq#q-declarable)
-it owns or imports from other NgModules.
-It doesn't declare or export any other kind of class.
-
-The NgModule is also special in another way.
-Unlike JavaScript modules, an NgModule can extend the _entire_ application with services
-by adding providers to the `@NgModule.providers` list.
-
-
-
-
-
-The provided services don't belong to the NgModule nor are they scoped to the declared classes.
-They are available _everywhere_.
-
-
-
-Here's an _@NgModule_ class with imports, exports, and declarations.
-
-
-
-
-Of course you use _JavaScript_ modules to write NgModules as seen in the complete `contact.module.ts` file:
-
-
-
+For more information, see [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
-{@a q-template-reference}
+
## How does Angular find components, directives, and pipes in a template? What is a template reference?
The [Angular compiler](guide/ngmodule-faq#q-angular-compiler) looks inside component templates
-for other components, directives, and pipes. When it finds one, that's a "template reference".
+for other components, directives, and pipes. When it finds one, that's a template reference.
-The Angular compiler finds a component or directive in a template when it can match the *selector* of that
-component or directive to some HTML in that template.
+The Angular compiler finds a component or directive in a template when it can match the *selector* of that component or directive to some HTML in that template.
The compiler finds a pipe if the pipe's *name* appears within the pipe syntax of the template HTML.
-Angular only matches selectors and pipe names for classes that are declared by this NgModule
-or exported by an NgModule that this one imports.
+Angular only matches selectors and pipe names for classes that are declared by this module
+or exported by a module that this module imports.
-{@a q-angular-compiler}
+
+
+{@ q-angular-compiler}
## What is the Angular compiler?
The Angular compiler converts the application code you write into highly performant JavaScript code.
-The `@NgModule` metadata play an important role in guiding the compilation process.
+The `@NgModule` metadata plays an important role in guiding the compilation process.
-The code you write isn't immediately executable.
-Consider *components*.
-Components have templates that contain custom elements, attribute directives, Angular binding declarations,
+The code you write isn't immediately executable. For example, components have templates that contain custom elements, attribute directives, Angular binding declarations,
and some peculiar syntax that clearly isn't native HTML.
The Angular compiler reads the template markup,
@@ -1166,214 +663,9 @@ A component factory creates a pure, 100% JavaScript representation
of the component that incorporates everything described in its `@Component` metadata:
the HTML, the binding instructions, the attached styles.
-Because *directives* and *pipes* appear in component templates,
+Because directives and pipes appear in component templates,
the Angular compiler incorporates them into compiled component code too.
`@NgModule` metadata tells the Angular compiler what components to compile for this module and
-how to link this module with other NgModules.
+how to link this module with other modules.
-
-
-{@a q-ngmodule-api}
-
-## @NgModule API
-
-The following table summarizes the `@NgModule` metadata properties.
-
-
-
-
-
-
- Property
-
-
-
- Description
-
-
-
-
-
-
-
- declarations
-
-
-
-
-
- A list of [declarable](guide/ngmodule-faq#q-declarable) classes,
- the *component*, *directive*, and *pipe* classes that _belong to this NgModule_.
-
- These declared classes are visible within the NgModule but invisible to
- components in a different NgModule unless they are _exported_ from this NgModule and
- the other NgModule _imports_ this one.
-
- Components, directives, and pipes must belong to _exactly_ one NgModule.
- The compiler emits an error if you try to declare the same class in more than one NgModule.
-
- *Do not re-declare a class imported from another NgModule.*
-
-
-
-
-
-
-
-
- providers
-
-
-
-
-
- A list of dependency-injection providers.
-
- Angular registers these providers with the root injector of the NgModule's execution context.
- That's the application's root injector for all NgModules loaded when the application starts.
-
- Angular can inject one of these provider services into any component in the application.
- If this NgModule or any NgModule loaded at launch provides the `HeroService`,
- Angular can inject the same `HeroService` intance into any app component.
-
- A lazy-loaded NgModule has its own sub-root injector which typically
- is a direct child of the application root injector.
-
- Lazy-loaded services are scoped to the lazy module's injector.
- If a lazy-loaded NgModule also provides the `HeroService`,
- any component created within that module's context (such as by router navigation)
- gets the local instance of the service, not the instance in the root application injector.
-
- Components in external NgModules continue to receive the instance created for the application root.
-
-
-
-
-
-
-
-
- imports
-
-
-
-
-
- A list of supporting NgModules.
-
- Specifically, the list of NgModules whose exported components, directives, or pipes
- are referenced by the component templates declared in this NgModule.
-
- A component template can [reference](guide/ngmodule-faq#q-template-reference) another component, directive, or pipe
- when the referenced class is declared in this module
- or the class was imported from another module.
-
- A component can use the `NgIf` and `NgFor` directives only because its declaring NgModule
- imported the Angular `CommonModule` (perhaps indirectly by importing `BrowserModule`).
-
- You can import many standard directives with the `CommonModule`
- but some familiar directives belong to other NgModules.
- A component template can bind with `[(ngModel)]` only after importing the Angular `FormsModule`.
-
-
-
-
-
-
-
- exports
-
-
-
-
-
- A list of declarations—*component*, *directive*, and *pipe* classes—that
- an importing NgModule can use.
-
- Exported declarations are the module's _public API_.
- A component in another NgModule can [reference](guide/ngmodule-faq#q-template-reference) _this_ NgModule's `HeroComponent`
- if it imports this module and this module exports `HeroComponent`.
-
- Declarations are private by default.
- If this NgModule does _not_ export `HeroComponent`, no other NgModule can see it.
-
- Importing an NgModule does _not_ automatically re-export the imported NgModule's imports.
- NgModule 'B' can't use `ngIf` just because it imported NgModule `A` which imported `CommonModule`.
- NgModule 'B' must import `CommonModule` itself.
-
- An NgModule can list another NgModule among its `exports`, in which case
- all of that NgModule's public components, directives, and pipes are exported.
-
- [Re-export](guide/ngmodule-faq#q-re-export) makes NgModule transitivity explicit.
- If NgModule 'A' re-exports `CommonModule` and NgModule 'B' imports NgModule 'A',
- NgModule 'B' components can use `ngIf` even though 'B' itself didn't import `CommonModule`.
-
-
-
-
-
-
-
-
- bootstrap
-
-
-
-
-
- A list of components that can be bootstrapped.
-
- Usually there's only one component in this list, the _root component_ of the application.
-
- Angular can launch with multiple bootstrap components,
- each with its own location in the host web page.
-
- A bootstrap component is automatically an `entryComponent`.
-
-
-
-
-
-
-
-
- entryComponents
-
-
-
-
-
- A list of components that are _not_ [referenced](guide/ngmodule-faq#q-template-reference) in a reachable component template.
-
- Most developers never set this property.
- The [Angular compiler](guide/ngmodule-faq#q-angular-compiler) must know about every component actually used in the application.
- The compiler can discover most components by walking the tree of references
- from one component template to another.
-
- But there's always at least one component that's not referenced in any template:
- the root component, `AppComponent`, that you bootstrap to launch the app.
- That's why it's called an _entry component_.
-
- Routed components are also _entry components_ because they aren't referenced in a template either.
- The router creates them and drops them into the DOM near a ``.
-
- While the bootstrapped and routed components are _entry components_,
- you usually don't have to add them to a module's `entryComponents` list.
-
- Angular automatically adds components in the module's `bootstrap` list to the `entryComponents` list.
- The `RouterModule` adds routed components to that list.
-
- That leaves only the following sources of undiscoverable components:
-
- * Components bootstrapped using one of the imperative techniques.
- * Components dynamically loaded into the DOM by some means other than the router.
-
- Both are advanced techniques that few developers ever employ.
- If you are one of those few, you must add these components to the
- `entryComponents` list yourself, either programmatically or by hand.
-
-
-
-
-
diff --git a/aio/content/guide/ngmodule-vs-jsmodule.md b/aio/content/guide/ngmodule-vs-jsmodule.md
new file mode 100644
index 0000000000..4b9832ac9f
--- /dev/null
+++ b/aio/content/guide/ngmodule-vs-jsmodule.md
@@ -0,0 +1,80 @@
+# JavaScript Modules vs. NgModules
+
+#### Prerequisites
+A basic understanding of [Bootstrapping](guide/bootstrapping).
+
+
+
+JavaScript and Angular use modules to organize code, and
+though they organize it differently, Angular apps rely on both.
+
+## JavaScript modules
+
+In JavaScript, modules are individual files with JavaScript code in them. To make what’s in them available, you write an export statement, usually after the relevant code, like this:
+
+```javascript
+export class AppComponent { ... }
+```
+
+Then, when you need that file’s code in another file, you import it like this:
+
+```javascript
+import { AppComponent } from './app.component';
+```
+
+JavaScript modules help you namespace, preventing accidental global variables.
+
+## NgModules
+
+
+NgModules are classes decorated with `@NgModule`. The `@NgModule` decorator’s `imports` array tells Angular what other NgModules the current module needs. The modules in the imports array are different than JavaScript modules because they are NgModules rather than regular JavaScript modules. Classes with an `@NgModule` decorator are by convention kept in their own files, but what makes them an `NgModule` isn’t being in their own file, like JavaScript modules; it’s the presence of `@NgModule` and its metadata.
+
+The `AppModule` generated from the Angular CLI demonstrates both kinds of modules in action:
+
+```javascript
+/* These are JavaScript import statements. Angular doesn’t know anything about these. */
+import { BrowserModule } from '@angular/platform-browser';
+import { NgModule } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HttpModule } from '@angular/http';
+
+import { AppComponent } from './app.component';
+
+/* The @NgModule decorator lets Angular know that this is an NgModule. */
+@NgModule({
+declarations: [
+ AppComponent
+],
+imports: [ /* These are NgModule imports. */
+ BrowserModule,
+ FormsModule,
+ HttpModule
+],
+providers: [],
+bootstrap: [AppComponent]
+})
+export class AppModule { }
+```
+
+
+The NgModule classes differ from JavaScript module classes in the following key ways:
+
+* An NgModule bounds [declarable classes](guide/ngmodule-faq#q-declarable) only.
+Declarables are the only classes that matter to the [Angular compiler](guide/ngmodule-faq#q-angular-compiler).
+* Instead of defining all member classes in one giant file as in a JavaScript module,
+you list the module's classes in the `@NgModule.declarations` list.
+* An NgModule can only export the [declarable classes](guide/ngmodule-faq#q-declarable)
+it owns or imports from other modules. It doesn't declare or export any other kind of class.
+* Unlike JavaScript modules, an NgModule can extend the _entire_ application with services
+by adding providers to the `@NgModule.providers` list.
+
+
+
+## More on NgModules
+
+For more information on NgModules, see:
+* [Bootstrapping](guide/bootstrapping).
+* [Frequently used modules](guide/frequent-ngmodules).
+* [Providers](guide/providers).
+
+
diff --git a/aio/content/guide/ngmodule.md b/aio/content/guide/ngmodule.md
deleted file mode 100644
index 5d00bdbb4c..0000000000
--- a/aio/content/guide/ngmodule.md
+++ /dev/null
@@ -1,1430 +0,0 @@
-# NgModules
-
-**NgModules** help organize an application into cohesive blocks of functionality.
-
-
-An NgModule is a class adorned with the **@NgModule** decorator function.
-`@NgModule` takes a metadata object that tells Angular how to compile and your code.
-It identifies the module's own components, directives, and pipes,
-making some of them public so external components can use them.
-`@NgModule` may add service providers to the application dependency injectors.
-And there are many more options covered here.
-
-{@a bootstrap}
-
-For a quick overview of NgModules, consider reading the
-[Bootstrapping](guide/bootstrapping) guide, which introduces NgModules and the essentials
-of creating and maintaining a single root `AppModule` for the entire application.
-
-_This_ page covers NgModules in greater depth.
-
-#### Live examples
-This page explains NgModules through a progression of improvements to a sample with a "Heroes" theme.
-Here's an index to live examples at key moments in the evolution of the sample:
-
-* The initial app
-* The first contact module
-* The revised contact module
-* Just before adding SharedModule
-* The final version
-
-#### Frequently asked questions (FAQs)
-
-This page covers NgModule concepts in a tutorial fashion.
-
-The companion [NgModule FAQs](guide/ngmodule-faq "NgModule FAQs") guide
-offers answers to specific design and implementation questions.
-Read this page before reading those FAQs.
-
-
-
-{@a angular-modularity}
-
-## Angular modularity
-
-NgModules are a great way to organize an application and extend it with capabilities from external libraries.
-
-Many Angular libraries are NgModules (such as `FormsModule`, `HttpModule`, and `RouterModule`).
-Many third-party libraries are available as NgModules (such as
-Material Design,
-Ionic,
-AngularFire2).
-
-NgModules consolidate components, directives, and pipes into
-cohesive blocks of functionality, each focused on a
-feature area, application business domain, workflow, or common collection of utilities.
-
-NgModules can also add services to the application.
-Such services might be internally developed, such as the application logger.
-Services can come from outside sources, such as the Angular router and Http client.
-
-NgModules can be loaded eagerly when the application starts.
-They can also be _lazy-loaded_ asynchronously by the router.
-
-An NgModule is a class decorated with `@NgModule` metadata.
-By setting metadata properties you tell Angular how your application parts fit together.
-For example, you can do the following:
-
-* _Declare_ which components, directives, and pipes belong to the NgModule.
-* _Export_ some of those classes so that other component templates can use them.
-* _Import_ other NgModules with the components, directives, and pipes needed by the components in _this_ NgModule.
-* _Provide_ services at the application level that any application component can use.
-* _Bootstrap_ the app with one or more top-level, _root_ components.
-
-{@a root-module}
-
-## The root _AppModule_
-
-Every Angular app has at least one NgModule class, the _root module_.
-You bootstrap _that_ NgModule to launch the application.
-
-By convention, the *root module* class is called `AppModule` and it exists in a file named `app.module.ts`.
-The [**Angular CLI**](https://cli.angular.io/) generates the initial `AppModule` for you when you create a project.
-
-
-ng new quickstart
-
-
-The root `AppModule` is all you need in a simple application with a few components.
-
-As the app grows, you may refactor the root `AppModule` into [*feature modules*](#feature-modules)
-that represent collections of related functionality.
-For now, stick with the root `AppModule` created by the CLI.
-
-
-
-
-The initial `declarations` array identifies the application's only component, `AppComponent`,
-the _root component_ at the top of the app's component tree.
-
-Soon you'll declare more [components](#declare-component)
-(and [directives](#declare-directive) and [pipes](#declare-pipe) too).
-
-The `@NgModule` metadata `imports` a single helper module, `BrowserModule`, which every browser app must import.
-`BrowserModule` registers critical application service providers.
-It also includes common directives like `NgIf` and `NgFor`, which become immediately visible and usable
-in any of this NgModule's component templates.
-
-The `providers` array registers services with the top-level [_dependency injector_](guide/dependency-injection).
-There are no services to register ... yet.
-
-Lastly, the `bootstrap` list identifies the `AppComponent` as the _bootstrap component_.
-When Angular launches the app, it renders the `AppComponent`
-inside the `` element tag of the `index.html`.
-
-Learn about that in the [bootstrapping](guide/bootstrapping) guide.
-
-
-
-The CLI-generated `AppComponent` in this guide's sample has been simplified and consolidated into a single `app.component.ts` file like this:
-
-
-
-
-
-
-Run the app and follow along with the steps in this guide:
-
-
-ng serve
-
-
-
-
-{@a declarations}
-{@a declare-directive}
-
-## Declare directives
-
-{@a declarables}
-
-As the app evolves, you'll add directives, components, and pipes (the _declarables_).
-You must declare each of these classes in an NgModule.
-
-As an exercise, begin by adding a `highlight.directive.ts` to the `src/app/` folder _by hand_.
-
-
-
-
-The `HighlightDirective` is an [attribute directive](guide/attribute-directives)
-that sets the background color of its host element.
-Update the `AppComponent` template to attach this directive to the `
` title element:
-
-
-
-
-The screen of the running app has not changed.
-The `
` is not highlighted.
-Angular does not yet recognize the `highlight` attribute and is ignoring it.
-You must declare the `HighlightDirective` in `AppModule`.
-
-Edit the `app.module.ts` file, import the `HighlightDirective`,
-and add it to the `AppModule` _declarations_ like this:
-
-
-
-
-The Angular CLI would have done all of this for you
-if you'd created the `HighlightDirective` with the CLI command like this:
-
-
-ng generate directive highlight
-
-
-But you didn't.
-You created the file by hand so you must declare the directive by hand.
-
-{@a declare-component}
-
-## Declare components
-
-Now add a `TitleComponent` to the app and this time create it with the CLI.
-
-
-ng generate component title --flat --no-spec --inline-style
-
-
-
-
-The `--flat` flag tells the CLI to generate all files to the `src/app/` folder.
-The `--no-spec` flag skips the test (`.spec`) file.
-The `--inline-style` flag prevents generation of the `.css` file (which you won't need).
-
-
-
-
-
-To see which files would be created or changed by any `ng generate` command, append the `--dryRun` flag (`-d` for short).
-
-
-
-Open the `AppModule` and look at the `declarations` where you will see that the CLI added
-the `TitleComponent` for you.
-
-
-
-
-Now rewrite the `title.component.html` like this.
-
-
-
-
-And move the `title` property from `app.component.ts` into the `title.component.ts`, which looks as follows after a little cleanup.
-
-
-
-
-Rewrite `AppComponent` to display the new `TitleComponent` in the `` element and get rid of the `title` property.
-
-
-
-
-#### Error if component not declared
-
-There was no visible clue when you neglected to declare the `HighlightDirective` attribute directive.
-The Angular compiler doesn't recognize `highlight` as an `
` attribute but it doesn't complain either.
-You'd discover it was undeclared only if you were looking for its effect.
-
-Now try removing the declaration of the `TitleComponent` from `AppModule`.
-
-The Angular compiler behaves differently when it encounters an unrecognized HTML element.
-The app ceases to display the page and
-the browser console logs the following error
-
-
-Uncaught Error: Template parse errors:
-'app-title' is not a known element:
-1. If 'app-title' is an Angular component, then verify that it is part of this NgModule.
-2. If 'app-title' is a Web Component then add 'CUSTOM_ELEMENTS_SCHEMA' to the '@NgModule.schemas' of this component to suppress this message.
-
-
-
-
-If you don't get that error, you might get this one:
-
-
-Uncaught Error: Component TitleComponent is not part of any NgModule or the module has not been imported into your module.
-
-
-
-
-**Always declare your [components](#declare-component), [directives](#declare-directive), and [pipes](#declare-pipe)**.
-
-{@a providers}
-
-## Service providers
-
-The [Dependency Injection](guide/dependency-injection) page describes
-the Angular hierarchical dependency-injection system and how to configure that system
-with [providers](guide/dependency-injection#providers).
-
-### NgModule providers
-
-An NgModule can provide services.
-A single instance of each provided service becomes available for injection into every class created with that NgModule's injector (or one of its descendant injectors).
-
-When Angular boots the application,
-it creates the root `AppModule` with a root dependency injector.
-Angular configures the root injector with the providers specified in the module's `@NgModule.providers`.
-
-Later, when Angular creates a new instance of a class— be it a component, directive, service, or module— that new class can be injected with an instance of a service provided to the root injector by the `AppModule`.
-
-
-
-Angular also configures the root injector with the providers specified by [imported NgModules](#imports).
-An NgModule's own providers are registered _after_ imported NgModule providers.
-When there are multiple providers for the same injection token, the last registration wins.
-
-
-
-### Compared to Component providers
-
-Providing a service in `@Component.providers` metadata means that a new service instance will be created for each new instance of _that_ component and will be available for injection into _all of that component instance's descendant sub-components_.
-
-The service instance won't be injected into any other component instances.
-Other instances of the same component class cannot see it.
-Sibling and ancestor component instances cannot see it.
-
-Component providers always supersede NgModule providers.
-A component provider for injection token `X` creates a new service instance that "shadows" an NgModule provider for injection token `X`.
-When the component or any of its sub-components inject `X`, they get the _component_ service instance, not the _NgModule_ service instance.
-
-Should you provide a service in an _NgModule_ or a _component_?
-The answer depends on how you want to scope the service.
-If the service should be widely available, provide it in an NgModule.
-If it should be visible only within a component tree, provide it in the component at the root of that tree.
-
-### NgModule provider example
-
-Many applications capture information about the currently logged-in user and make that information
-accessible through a user service.
-
-Use the CLI to create a `UserService` and provide it in the root `AppModule`.
-
-
-ng generate service user --module=app
-
-
-This command creates a skeleton `UserService` in `src/app/user.service.ts` and a companion test file, `src/app/user.service.spec.ts`.
-
-The `--module=app` flag tells the CLI to provide the service class in the NgModule defined in the `src/app/app.module.ts` file.
-
-If you omit the `--module` flag, the CLI still creates the service but _does not provide it_ anywhere.
-You have to do that yourself.
-
-Confirm that the `--module=app` flag did provide the service in the root `AppModule` by inspecting the `@NgModule.providers` array in `src/app/app.module.ts`
-
-
-
-
-Replace the generated contents of `src/app/user.service.ts` with the following dummy implementation.
-
-
-
-
-Update the `TitleComponent` class with a constructor that injects the `UserService`
-and sets the component's `user` property from the service.
-
-
-
-
-Update the `TitleComponent` template to show the welcome message below the application title.
-
-
-
-
-{@a imports}
-
-## NgModule imports
-
-In the revised `TitleComponent`, an `*ngIf` directive guards the message.
-There is no message if there is no user.
-
-
-
-
-Although `AppModule` doesn't declare the `NgIf` directive, the application still compiles and runs.
-How can that be? The Angular compiler should either ignore or complain about unrecognized HTML.
-
-### Importing _BrowserModule_
-
-Angular does recognize `NgIf` because the `AppModule` imports it indirectly
-when it imports `BrowserModule`.
-
-
-
-
-
-Importing `BrowserModule` made all of its public components, directives, and pipes visible
-to the templates of components declared in `AppModule`, which include `TitleComponent`.
-
-{@a reexport}
-
-### Re-exported NgModules
-
-The `NgIf` directive isn't declared in `BrowserModule`.
-It's declared in `CommonModule` from `@angular/common`.
-
-`CommonModule` contributes many of the common directives that applications need, including `ngIf` and `ngFor`.
-
-`AppModule` doesn't import `CommonModule` directly.
-But it benefits from the fact that `BrowserModule` imports `CommonModule`
-**and [re-exports](guide/ngmodule-faq#q-re-export) it**.
-
-The net effect is that an importer of `BrowserModule` gets `CommonModule` directives automatically as if it had declared them itself.
-
-Many familiar Angular directives don't belong to `CommonModule`.
-For example, `NgModel` and `RouterLink` belong to Angular's `FormsModule` and `RouterModule` respectively.
-You must import those NgModules before you can use their directives.
-
-To illustrate this point, you'll extend the sample app with _contact editor_ whose `ContactComponent` is a form component.
-You'll have to import form support from the Angular `FormsModule`.
-
-{@a add-contact-editor}
-
-### Add a _contact editor_
-
-Imagine that you added the following _contact editor_ files
-to the project by hand _without the help of the CLI_.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Form components are often complex and this is one is no exception.
-To make it manageable, all contact-related files are in an `src/app/contact` folder.
-
-The `ContactComponent` implementation is spread over three constituent HTML, TypeScript, and css files.
-
-There's a [custom pipe](guide/pipes#custom-pipes) (called `Awesome`),
-a `ContactHighlightDirective`, and a `ContactService` for fetching contacts.
-
-The `ContactService` was added to the `AppModule` providers.
-
-
-
-
-Now any class can inject the application-wide instances of the `ContactService` and `UserService`.
-
-
-
-### Import supporting _FormsModule_
-
-The `ContactComponent` is written with Angular forms in the [template-driven](guide/forms#template-driven) style.
-
-Notice the `[(ngModel)]` binding in the middle of the component template, `contact.component.html`.
-
-
-
-
-Two-way data binding `[(ngModel)]`is typical of the _template-driven_ style.
-The `ngModel` is the selector for the `NgModel` directive.
-Although `NgModel` is an Angular directive,
-the _Angular compiler_ won't recognize it for two reasons:
-
-1. `AppModule` doesn't declare `NgModel` (and shouldn't).
-2. `NgModel` wasn't imported via `BrowserModule`.
-
-`ContactComponent` wouldn't behave like an Angular form anyway because
-form features such as validation aren't part of the Angular core.
-
-To correct these problems, the `AppModule` must import _both_ the `BrowserModule`
-_and_ the **FormsModule from '@angular/forms'** like this.
-
-
-
-
-
-
-You can write Angular form components in template-driven or [reactive](guide/reactive-forms) style.
-NgModules with components written in the _reactive_ style
-import the `ReactiveFormsModule`.
-
-
-
-Now `[(ngModel)]` binding will work and the user input will be validated by Angular forms,
-once you [declare the new component, pipe, and directive](#declare-pipe).
-
-### Never re-declare
-
-Importing the `FormsModule` makes the `NgModelDirective` (and all of the other `FORMS_DIRECTIVES`) available to components declared in `AppModule`.
-
-*Do not also* add these directives to the `AppModule` metadata's declarations.
-
-
-
-**Never re-declare classes that belong to another NgModule.**
-Components, directives, and pipes should be declared in _exactly one NgModule_.
-
-
-
-{@a declare-pipe}
-
-## Declare pipes
-
-The revised application still won't compile until you declare the contact component, directive, and pipe.
-
-Components and directives are *declarables*. So are **pipes**.
-
-You [learned earlier](#declarations) to generate and declare both components and directives with the CLI `ng generate` commands.
-
-There's also a CLI command to generate and declare the `AwesomePipe`:
-
-
-ng generate pipe awesome
-
-
-However, if you write these class files by hand or opt-out of declaration with the `--skip-import` flag, you'll have to add the declarations yourself.
-
-[You were told](#add-contact-editor) to add the _contact editor_ files by hand, so
-you must manually update the `declarations` in the `AppModule`:
-
-
-
-
-
Display the ContactComponent
-
-Update the `AppComponent` template to display the `ContactComponent` by placing an
-element with its selector (``) just below the title.
-
-
-
-
-
Run the app
-Everything is in place to run the application with its contact editor.
-
-Try the example:
-
-
-
-## Selector conflicts
-
-Look closely at the screen.
-Notice that the background of the application title text is _blue_.
-It should be _gold_ (see `src/app/app.component.html`).
-
-Only the contact name should be blue (see `src/app/contact/contact.component.html`).
-
-What went wrong?
-
-This application defines two highlight directives that
-set the background color of their host elements with a different color (gold and blue).
-
-One is defined at the root level (`src/app/highlight.directive.ts`);
-the other is in the contact editor folder (`src/app/contact/contact-highlight.directive.ts`).
-
-Their class names are different (`HighlightDirective` and `ContactHighlightDirective`)
-but their selectors both match any HTML element with a `highlight` attribute.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Both directives are declared in the same `AppModule` so both directives are active
-for all components declared in `AppModule`.
-
-There's nothing intrinsically wrong with multiple directives selecting the same element.
-Each could modify the element in a different, non-conflicting way.
-
-In _this case_, both directives compete to set the background color of the same element.
-The directive that's declared later (`ContactHighlightDirective`) always wins because its DOM changes overwrite the changes by the earlier `HighlightDirective`.
-
-The `ContactHighlightDirective` will make the application title text blue
-when it should be gold.
-Only the contact name should be blue (see `src/app/contact/contact.component.html`).
-
-If you cannot rename the selectors, you can resolve the conflicts by creating [feature modules](#feature-modules)
-that insulate the declarations in one NgModule from the declarations in another.
-
-
-
-While it is legal to declare two _directives_ with the same selector in the same NgModule,
-the compiler will not let you declare two _components_ with the same selector in the same NgModule because it **cannot insert multiple components in the same DOM location**.
-
-Nor can you _import_ an NgModule that declares the same selector as another component in this NgModule.
-The reason is the same: an HTML element may be controlled by at most one Angular component.
-
-Either rename the selectors or use [feature modules](#feature-modules) to eliminate the conflict.
-
-
-
-## Feature modules
-
-This tiny app is already experiencing structural issues.
-
-* The root `AppModule` grows larger with each new application class.
-
-
-* There are conflicting directives.
-The `ContactHighlightDirective` in the contact re-colors the work done by the `HighlightDirective` declared in `AppModule` and colors the application title text when it should color only the `ContactComponent`.
-
-
-* The app lacks clear boundaries between contact functionality and other application features.
-That lack of clarity makes it harder to assign development responsibilities to different teams.
-
-_Feature modules_ can help resolve these issues.
-
-Architecturally, a feature module is an NgModule class that is dedicated to an application feature or workflow.
-Technically, it's another class adorned by the `@NgModule` decorator, just like a root `AppModule`.
-
-Feature module metadata have the same properties as root module metadata.
-When loaded together, the root module and the feature module share the same dependency injector,
-which means the services provided in a feature module are available to all.
-
-These two module types have the following significant technical differences:
-
-* You _boot_ the root module to _launch_ the app;
-you _import_ a feature module to _extend_ the app.
-* A feature module can expose or hide its [declarables](#declarables) from other NgModules.
-
-Otherwise, a feature module is distinguished primarily by its intent.
-
-A feature module delivers a cohesive set of functionality
-focused on an application business domain, user workflow, facility (forms, http, routing),
-or collection of related utilities.
-Feature modules help you partition the app into areas of specific interest and purpose.
-
-A feature module collaborates with the root module and with other NgModules
-through the services it provides and
-the components, directives, and pipes that it shares.
-
-{@a contact-module-v1}
-
-
Make contact editor a feature
-
-In this section, you refactor the _contact editor_ functionality out of the root `AppModule`
-and into a dedicated feature module by following these steps.
-
-1. Create the `ContactModule` feature module in its own folder.
-1. Copy the _contact editor_ declarations and providers from `AppModule` to `ContactModule`.
-1. Export the `ContactComponent`.
-1. Import the `ContactModule` into the `AppModule`.
-1. Cleanup the `AppModule`.
-
-You'll create one new `ContactModule` class and change one existing `AppModule` class.
-All other files are untouched.
-
-### Create the feature module
-
-Generate the _ContactModule_ and its folder with an Angular CLI command.
-
-
-ng generate module contact
-
-
-Here's the generated `ContactModule`.
-
-
-
-
-After modifying the initial `ContactsModule` as outlined above, it looks like this.
-
-
-
-
-The following sections discuss the important changes.
-
-### Import _CommonModule_
-
-Notice that `ContactModule` imports `CommonModule`, not `BrowserModule`.
-The CLI module generation took care of this for you.
-
-Feature module components need the common Angular directives but
-not the services and bootstrapping logic in `BrowserModule`.
-See the [NgModule FAQs](guide/ngmodule-faq#q-browser-vs-common-module)
-for more details.
-
-### Import _FormsModule_
-
-The `ContactModule` imports the `FormsModule`
-because its `ContactComponent` uses `NgModel`,
-one of the `FormsModule` directives.
-
-
-
-NgModules don't inherit access to the declarations of the root `AppModule` or any other NgModule.
-Each NgModule must import what it needs.
-Because `ContactComponent` needs the form directives,
-its `ContactModule` must import `FormsModule`.
-
-
-
-
Copy declarations
-
-The `ContactModule` declares the _contact editor_ components, directives and pipes.
-
-
-
-The app fails to compile at this point, in part because
-`ContactComponent` is currently declared in both the `AppModule` and the `ContactModule`.
-A component may only be declared in one NgModule.
-You'll fix this problem shortly.
-
-
-
-{@a root-scoped-providers}
-
-### Providers are root-scoped
-
-The `ContactModule` provides the `ContactService` and the `AppModule` will stop providing it [after refactoring](#refactor-appmodule).
-
-Architecturally, the `ContactService` belongs to the _contact editor_ domain.
-Classes in the rest of the app do not need the `ContactService` and shouldn't inject it.
-So it makes sense for the `ContactModule` to provide the `ContactService` as it does.
-
-You might expect that the `ContactService` would only be injectable in classes declared or provided in the `ContactModule`.
-
-That's not the case.
-_Any_ class _anywhere_ can inject the `ContactService`
-because `ContactModule` providers are _root_-scoped.
-
-
-
-To be precise, all _eagerly loaded_ modules— modules loaded when the application starts — are root-scoped.
-This `ContactModule` is eagerly loaded.
-
-You will learn that services provided in [_lazy-loaded_ modules](#lazy-loaded-modules)
-have their own scope.
-
-
-
-Angular does not have _module_-scoping mechanism.
-Unlike components, NgModule instances do not have their own injectors
-so they can't have their own provider scopes.
-
-`ContactService` remains an _application_-scoped service because Angular
-registers all NgModule `providers` with the application's *root injector*.
-This is true whether the service is provided directly in the root `AppModule`
-or in an imported feature module like `ContactModule`.
-
-In practice, service scoping is rarely an issue.
-Components don't accidentally inject a service.
-To inject the `ContactService`, you'd have to import its _type_
-and explicitly inject the service into a class constructor.
-Only _contact editor_ components should import the `ContactService` type.
-
-If it's really important to you to restrict the scope of a service,
-provide it in the feature's top-level component (`ContactComponent` in this case).
-
-For more on this topic, see "[How do I restrict service scope to a module?](guide/ngmodule-faq#q-component-scoped-providers)"
-in the [NgModule FAQs](guide/ngmodule-faq).
-
-### Export public-facing components
-
-The `ContactModule` makes the `ContactComponent` _public_ by _exporting_ it.
-
-
-
-
-Declared classes are _private_ by default.
-Private [declarables](#declarables) may only appear in the templates of components declared by the _same_ NgModule.
-They are invisible to components in _other_ NgModules.
-
-That's a problem for the `AppComponent`.
-Both components _used to be_ declared in `AppModule` so Angular could
-display the `ContactComponent` within the `AppComponent`.
-Now that the `ContactComponent` is declared in its own feature module.
-The `AppComponent` cannot see it unless it is public.
-
-The first step toward a solution is to _export_ the `ContactComponent`.
-The second step is to _import_ the `ContactModule` in the `AppModule`,
-which you'll do when you [refactor the _AppModule_](#refactor-appmodule).
-
-The `AwesomePipe` and `ContactHighlightDirective` remain private and are hidden from the rest of the application.
-
-The `ContactHighlightDirective`, being private, no longer overrides the `HighlightDirective` in the `AppComponent`. The background of the title text is gold as intended.
-
-{@a refactor-appmodule}
-### Refactor the _AppModule_
-
-Return to the `AppModule` and remove everything specific to the _contact editor_ feature set.
-Leave only the classes required at the application root level.
-
-* Delete the _contact editor_ import statements.
-* Delete the _contact editor_ declarations and providers.
-* Delete the `FormsModule` from the `imports` list (the `AppComponent` doesn't need it).
-* Import the `ContactModule` so the app can continue to display the exported `ContactComponent`.
-
-Here's the refactored `AppModule`, presented side-by-side with the previous version.
-
-
-
-
-
-
-
-
-
-
-
-### Improvements
-
-There's a lot to like in the revised `AppModule`.
-
-* It does not change as the _Contact_ domain grows.
-* It only changes when you add new NgModules.
-* It's simpler:
-
- * Fewer import statements.
- * No `FormsModule` import.
- * No _contact editor_ declarations.
- * No `ContactService` provider.
- * No _highlight directive_ conflicts.
-
-Try this `ContactModule` version of the sample.
-
-Try the live example.
-
-{@a routing-modules}
-{@a lazy-loaded-modules}
-
-## Routing modules
-
-Navigating the app with the [Angular Router](guide/router) reveals
-new dimensions of the NgModule.
-
-In this segment, you'll learn to write _routing modules_ that configure the router.
-You'll discover the implications of _lazy loading_ a feature module with the router's `loadChildren` method.
-
-Imagine that the sample app has evolved substantially along the lines of the
-[Tour of Heroes tutorial](tutorial).
-
-* The app has three feature modules: Contact, Hero (new), and Crisis (new).
-* The [Angular router](guide/router) helps users navigate among these modules.
-* The `ContactComponent` is the default destination when the app starts.
-* The `ContactModule` continues to be _eagerly loaded_ when the application starts.
-* `HeroModule` and the `CrisisModule` are _lazy-loaded_.
-
-There's too much code behind this sample app to review every line.
-Instead, the guide explores just those parts necessary to understand new aspects of NgModules.
-
-You can examine the complete source for this version of the app in
-the live example.
-
-{@a app-component-template}
-
-
The root AppComponent
-
-The revised `AppComponent` template has
-a title, three links, and a ``.
-
-
-
-
-The `` element that displayed the `ContactComponent` is gone; you're routing to the _Contact_ page now.
-
-
The root AppModule
-
-The `AppModule` is slimmer now.
-
-
-
-
-The `AppModule` is no longer aware of the application domains such as contacts, heroes, and crises.
-Those concerns are pushed down to `ContactModule`, `HeroesModule`, and `CrisisModule` respectively
-and only the routing configuration knows about them.
-
-The significant change from version 2 is the addition of the *AppRoutingModule* to the NgModule `imports`.
-The `AppRoutingModule` is a [routing module](guide/router#routing-module)
-that handles the app's routing concerns.
-
-### _AppRoutingModule_
-
-The router is the subject of the [Routing & Navigation](guide/router) guide, so this section skips many routing details and
-concentrates on the _intersection_ of NgModules and routing.
-
-You can specify router configuration directly within the root `AppModule` or within a feature module.
-
-The _Router guide_ recommends instead that you locate router configuration in separate, dedicated NgModules, called _routing modules_.
-You then import those routing modules into their corresponding root or feature modules.
-
-The goal is to separate the normal declarative concerns of an NgModule from the often complex router configuration logic.
-
-By convention, a routing module's name ends in `...RoutingModule`.
-The top-level root module is `AppModule` and it imports its companion _routing module_ called `AppRoutingModule`.
-
-
-
-
-Here is this app's `AppRoutingModule`, followed by a discussion.
-
-
-
-
-The `AppRoutingModule` defines three routes:
-
-
-
-
-The first route redirects the empty URL (such as `http://host.com/`)
-to another route whose path is `contact` (such as `http://host.com/contact`).
-
-The `contact` route isn't defined within the `AppRoutingModule`.
-It's defined in the _Contact_ feature's _own_ routing module, `ContactRoutingModule`.
-
-
-
-It's standard practice for feature modules with routing components to define their own routes.
-You'll get to [`ContactRoutingModule`](#contact-routing-module) in a moment.
-
-
-
-The remaining two routes use lazy loading syntax to tell the router where to find the modules for the hero and crisis features:
-
-
-
-
-
-
-A lazy-loaded NgModule location is a _string_, not a _type_.
-In this app, the string identifies both the NgModule _file_ and the NgModule _class_,
-the latter separated from the former by a `#`.
-
-
-
-### Routing module imports
-
-A _routing module_ typically imports the Angular `RouterModule` so it can register routes.
-
-It may also import a _feature module_ which registers routes (either directly or through its companion _routing module_).
-
-This `AppRoutingModule` does both.
-
-
-
-
-It first imports the `ContactModule`, which [as you'll see](#contact-routing-module),
-imports its own `ContactRoutingModule`.
-
-**Import order matters!**
-Because "contacts" is the first defined route and the default route for the app,
-you must import it _before_ all other routing-related modules.
-
-The second import registers the routes defined in this module
-by calling the `RouterModule.forRoot` class method.
-
-
-
-
-The `forRoot` method does two things:
-
-1. Configures the router with the supplied _routes_.
-1. Initializes the Angular router itself.
-
-
-
-Call `RouterModule.forRoot` exactly once for the entire app.
-
-Calling it in the `AppRoutingModule`, the companion to the root `AppModule`,
-is a good way to ensure that this method is called exactly once.
-
-Never call `RouterModule.forRoot` in a feature's _routing module_.
-
-
-
-### Re-export _RouterModule_
-
-All _routing modules_ should re-export the `RouterModule`.
-
-
-
-
-Re-exporting `RouterModule` makes the router directives
-available to the companion module that imports it.
-This is a considerable convenience for the importing module.
-
-For example, the `AppComponent` template relies on the
-[`routerLink`](guide/router#router-links) directive
-to turn the user's clicks into navigations.
-The Angular compiler only recognizes `routerLink` because
-
-- `AppComponent`is declared by `AppModule`,
-- `AppModule` imports `AppRoutingModule`,
-- `AppRoutingModule` exports `RouterModule`, and
-- `RouterModule` exports the `RouterLink` directive.
-
-If `AppRoutingModule` didn't re-export `RouterModule`, the `AppModule` would have to import the `RouterModule` itself.
-
-{@a contact-routing-module}
-
-### Routing to a feature module
-
-The three feature modules (`ContactModule`, `HeroModule`, `CrisisModule`)
-have corresponding routing modules (`ContactRoutingModule`, `HeroRoutingModule`, `CrisisRoutingModule`).
-
-They follow the same pattern as the `AppRoutingModule`.
-* define routes
-* register the routes with Angular's `RouterModule`
-* export the `RouterModule`.
-
-The `ContactRoutingModule` is the simplest of the three.
-It defines and registers a single route to the `ContactComponent`.
-
-
-
-
-There is **one critical difference** from `AppRoutingModule`:
-you pass the routes to `RouterModule.forChild`, not `forRoot`.
-
-
-
-Always call `RouterModule.forChild` in a feature-routing module.
-Never call `RouterModule.forRoot`.
-
-
-
-
-#### _ContactModule_ changes
-
-Because the app navigates to the `ContactComponent` instead of
-simply displaying it in the `AppComponent` template,
-the `ContactModule` has changed.
-
-* It imports the `ContactRoutingModule`.
-
-* It no longer exports `ContactComponent`.
-
-The `ContactComponent` is only displayed by the router,
-No template references its `` selector.
-There's no reason to make it public via the `exports` array.
-
-Here is the latest version, side-by-side with the previous version.
-
-
-
-
-
-
-
-
-
-
-
-
-{@a hero-module}
-
-### Lazy-loaded routing
-
-The `HeroModule` and `CrisisModule` have corresponding _routing modules_, `HeroRoutingModule` and `CrisisRoutingModule`.
-
-The app _lazy loads_ the `HeroModule` and the `CrisisModule`.
-That means the `HeroModule` and the `CrisisModule` are not loaded into the browser until the user navigates to their components.
-
-
-
-Do not import the `HeroModule` or `CrisisModule` or any of their classes outside of their respective file folders.
-If you do, you will unintentionally load those modules and all of their code
-when the application starts, defeating the purpose of lazy loading.
-
-For example, if you import the `HeroService` in `AppModule`,
-the `HeroService` class and all related hero classes will be loaded when the application starts.
-
-
-
-Lazy loading can improve the app's perceived performance because the browser doesn't have to process lazy-loaded code when the app starts.
-It may _never_ process that code.
-
-You cannot tell that these modules are lazy-loaded by looking at their _routing modules_.
-They happen to be a little more complex than `ContactRoutingModule`.
-For example, The `HeroRoutingModule` has [child routes](guide/router#child-routing-component).
-But the added complexity springs from intrinsic hero and crisis functionality, not from lazy loading.
-Fundamentally, these _routing modules_ are just like `ContactRoutingModule` and you write them the same way.
-
-{@a lazy-load-DI}
-### Lazy-loaded NgModule providers
-
-There is a **runtime difference** that can be significant.
-Services provided by lazy-loaded NgModules are only available to classes instantiated within the lazy-loaded context. The reason has to do with dependency injection.
-
-When an NgModule is _eagerly loaded_ as the application starts,
-its providers are added to the application's _root injector_.
-Any class in the application can inject a service from the _root injector_.
-
-When the router _lazy loads_ an NgModule, Angular instantiates the module
-with a _child injector_ (a descendant of the _root injector_)
-and adds the module's providers to this _child injector_.
-Classes created with the _child injector_ can inject one of its provided services.
-Classes created with _root injector_ cannot.
-
-Each of the three feature modules has its own data access service.
-Because the `ContactModule` is _eagerly loaded_ when the application starts,
-its `ContactService` is provided by the application's _root dependency injector_.
-That means the `ContactService` can be injected into any application class, including hero and crisis components.
-
-Because `CrisisModule` is _lazy-loaded_,
-its `CrisisService` is provided by the `CrisisModule` _child injector_.
-It can only be injected into one of the crisis components.
-No other kind of component can inject the `CrisisService` because no other kind of component can be reached along a route that lazy loads the `CrisisModule`.
-
-### Lazy-loaded NgModule lifetime
-
-Both eager and lazy-loaded NgModules are created _once_ and never destroyed.
-This means that their provided service instances are created _once_ and never destroyed.
-
-As you navigate among the application components, the router creates and destroys instances of the contact, hero, and crisis components.
-When these components inject data services provided by their modules,
-they get the same data service instance each time.
-
-If the `HeroService` kept a cache of unsaved changes and the user navigated to the `ContactComponent` or the `CrisisListComponent`, the pending hero changes would remain in the one `HeroService` instance, waiting to be saved.
-
-But if you provided the `HeroService` in the `HeroComponent` instead of the `HeroModule`, new `HeroService` instances would be created each time
-the user navigated to a hero component. Previously pending hero changes would be lost.
-
-To illustrate this point, the sample app provides the `HeroService` in the `HeroComponent` rather than the `HeroModule`.
-
-Run the app, open the browser development tools, and look at the console as you navigate among the feature pages.
-
-
-// App starts
-ContactService instance created.
-...
-// Navigate to Crisis Center
-CrisisService instance created.
-...
-// Navigate to Heroes
-HeroService instance created.
-...
-// Navigate to Contact
-HeroService instance destroyed.
-...
-// Navigate back to Heroes
-HeroService instance created.
-
-
-The console log shows the `HeroService` repeatedly created and destroyed.
-The `ContactService` and `CrisisService` are created but never destroyed, no matter where you navigate.
-
-#### Run it
-
-Try this routed version of the sample.
-
-Try the live example.
-
-{@a shared-module}
-
-## Shared modules
-
-The app is shaping up.
-But there are a few annoying problems.
-There are three unnecessarily different _highlight directives_
-and the many files cluttering the app folder level could be better organized.
-
-You can eliminate the duplication and tidy-up by writing a `SharedModule`
-to hold the common components, directives, and pipes.
-Then share this NgModule with the other NgModules that need these declarables.
-
-Use the CLI to create the `SharedModule` class in its `src/app/shared` folder.
-
-
-ng generate module shared
-
-
-Now refactor as follows:
-
-- Move the `AwesomePipe` from `src/app/contact` to `src/app/shared`.
-- Move the `HighlightDirective` from `src/app/hero` to `src/app/shared`.
-- Delete the _highlight directive_ classes from `src/app/` and `src/app/contact`.
-- Update the `SharedModule` as follows:
-
-
-
-
-Note the following:
-
-* It declares and exports the shared pipe and directive.
-* It imports and re-exports the `CommonModule` and `FormsModule`
-* It can re-export `FormsModule` without importing it.
-
-### Re-exporting NgModules
-
-Technically, there is no need for `SharedModule` to import `CommonModule` or `FormsModule`.
-`SharedModule` doesn't declare anything that needs material from `CommonModule` or `FormsModule`.
-
-But NgModules that would like to import `SharedModule` for its pipe and highlight directive happen also to declare components that need `NgIf` and `NgFor` from `CommonModule`
-and do two-way binding with `[(ngModel)]` from the `FormsModule`.
-
-Normally, they'd have to import `CommonModule` and `FormsModule` as well as `SharedModule`.
-Now they can just import `SharedModule`.
-By exporting `CommonModule` and `FormsModule`,
-`SharedModule` makes them available to its importers _for free_.
-
-#### A trimmer _ContactModule_
-
-See how `ContactModule` became more concise, compared to its previous version:
-
-
-
-
-
-
-
-
-
-
-
-Notice the following:
-
-* The `AwesomePipe` and `ContactHighlightDirective` are gone.
-* The imports include `SharedModule` instead of `CommonModule` and `FormsModule`.
-* The new version is leaner and cleaner.
-
-
-### Why _TitleComponent_ isn't shared
-
-`SharedModule` exists to make commonly used components, directives, and pipes available
-for use in the templates of components in many other NgModules.
-
-The `TitleComponent` is used only once by the `AppComponent`.
-There's no point in sharing it.
-
-{@a no-shared-module-providers}
-
-### Why _UserService_ isn't shared
-
-While many components share the same service instances,
-they rely on Angular dependency injection to do this kind of sharing, not the NgModule system.
-
-Several components of the sample inject the `UserService`.
-There should be only one instance of the `UserService` in the entire application
-and only one provider of it.
-
-`UserService` is an application-wide singleton.
-You don't want each NgModule to have its own separate instance.
-Yet there is [a real danger](guide/ngmodule-faq#q-why-bad) of that happening
-if the `SharedModule` provides the `UserService`.
-
-
-
-Do *not* specify app-wide singleton `providers` in a shared module.
-A lazy-loaded NgModule that imports that shared module makes its own copy of the service.
-
-
-
-{@a core-module}
-
-## The Core module
-
-At the moment, the root folder is cluttered with the `UserService`
-and `TitleComponent` that only appear in the root `AppComponent`.
-You didn't include them in the `SharedModule` for reasons just explained.
-
-Instead, gather them in a single `CoreModule` that you import once when the app starts
-and never import anywhere else.
-
-Perform the following steps:
-
-1. Create a `CoreModule` class in an `src/app/core` folder.
-1. Move the `TitleComponent` and `UserService` from `src/app/` to `src/app/core`.
-1. Declare and export the `TitleComponent`.
-1. Provide the `UserService`.
-1. Update the root `AppModule` to import `CoreModule`.
-
-Most of this work is familiar. The interesting part is the `CoreModule`.
-
-
-
-
-
-
-You're importing some extra symbols from the Angular core library that you're not using yet.
-They'll become relevant later in this page.
-
-
-
-The `@NgModule` metadata should be familiar.
-You declare the `TitleComponent` because this NgModule owns it.
-You export it because `AppComponent` (which is in `AppModule`) displays the title in its template.
-`TitleComponent` needs the Angular `NgIf` directive that you import from `CommonModule`.
-
-`CoreModule` provides the `UserService`. Angular registers that provider with the app root injector,
-making a singleton instance of the `UserService` available to any component that needs it,
-whether that component is eagerly or lazily loaded.
-
-
-
-
Why bother?
-
-This scenario is clearly contrived.
-The app is too small to worry about a single service file and a tiny, one-time component.
-
-A `TitleComponent` sitting in the root folder isn't bothering anyone.
-The root `AppModule` can register the `UserService` itself,
-as it does currently, even if you decide to relocate the `UserService` file to the `src/app/core` folder.
-
-Real-world apps have more to worry about.
-They can have several single-use components (such as spinners, message toasts, and modal dialogs)
-that appear only in the `AppComponent` template.
-You don't import them elsewhere so they're not shared in that sense.
-Yet they're too big and messy to leave loose in the root folder.
-
-Apps often have many singleton services like this sample's `UserService`.
-Each must be registered exactly once, in the app root injector, when the application starts.
-
-While many components inject such services in their constructors—and
-therefore require JavaScript `import` statements to import their symbols—no
-other component or NgModule should define or re-create the services themselves.
-Their _providers_ aren't shared.
-
-We recommend collecting such single-use classes and hiding their details inside a `CoreModule`.
-A simplified root `AppModule` imports `CoreModule` in its capacity as orchestrator of the application as a whole.
-
-
-
-#### A trimmer _AppModule_
-
-Here is the updated `AppModule` paired with version 3 for comparison:
-
-
-
-
-
-
-
-
-
-
-
-`AppModule` now has the following qualities:
-
-* A little smaller because many `src/app/root` classes have moved to other NgModules.
-* Stable because you'll add future components and providers to other NgModules, not this one.
-* Delegated to imported NgModules rather than doing work.
-* Focused on its main task, orchestrating the app as a whole.
-
-
-{@a core-for-root}
-
-### Configure core services with _CoreModule.forRoot_
-
-An NgModule that adds providers to the application can offer a facility for configuring those providers as well.
-
-By convention, the `forRoot` static method both provides and configures services at the same time.
-It takes a service configuration object and returns a
-[ModuleWithProviders](api/core/ModuleWithProviders), which is
-a simple object with the following properties:
-
-* `ngModule`: the `CoreModule` class
-* `providers`: the configured providers
-
-The root `AppModule` imports the `CoreModule` and adds the `providers` to the `AppModule` providers.
-
-
-
-More precisely, Angular accumulates all imported providers before appending the items listed in `@NgModule.providers`.
-This sequence ensures that whatever you add explicitly to the `AppModule` providers takes precedence
-over the providers of imported NgModules.
-
-
-
-Add a `CoreModule.forRoot` method that configures the core `UserService`.
-
-You've extended the core `UserService` with an optional, injected `UserServiceConfig`.
-If a `UserServiceConfig` exists, the `UserService` sets the user name from that config.
-
-
-
-
-Here's `CoreModule.forRoot` that takes a `UserServiceConfig` object:
-
-
-
-
-Lastly, call it within the `imports` list of the `AppModule`.
-
-
-
-
-The app displays "Miss Marple" as the user instead of the default "Sherlock Holmes".
-
-
-
-Call `forRoot` only in the root module, `AppModule`.
-Calling it in any other NgModule, particularly in a lazy-loaded NgModule,
-is contrary to the intent and can produce a runtime error.
-
-Remember to _import_ the result; don't add it to any other `@NgModule` list.
-
-
-
-
-
-{@a prevent-reimport}
-
-### Prevent reimport of the _CoreModule_
-
-Only the root `AppModule` should import the `CoreModule`.
-[Bad things happen](guide/ngmodule-faq#q-why-bad) if a lazy-loaded NgModule imports it.
-
-You could hope that no developer makes that mistake.
-Or you can guard against it and fail fast by adding the following `CoreModule` constructor.
-
-
-
-
-The constructor tells Angular to inject the `CoreModule` into itself.
-That seems dangerously circular.
-
-The injection would be circular if Angular looked for `CoreModule` in the _current_ injector.
-The `@SkipSelf` decorator means "look for `CoreModule` in an ancestor injector, above me in the injector hierarchy."
-
-If the constructor executes as intended in the `AppModule`,
-there is no ancestor injector that could provide an instance of `CoreModule`.
-The injector should give up.
-
-By default, the injector throws an error when it can't find a requested provider.
-The `@Optional` decorator means not finding the service is OK.
-The injector returns `null`, the `parentModule` parameter is null,
-and the constructor concludes uneventfully.
-
-It's a different story if you improperly import `CoreModule` into a lazy-loaded NgModule such as `HeroModule` (try it).
-
-Angular creates a lazy-loaded NgModule with its own injector, a _child_ of the root injector.
-`@SkipSelf` causes Angular to look for a `CoreModule` in the parent injector, which this time is the root injector.
-Of course it finds the instance imported by the root `AppModule`.
-Now `parentModule` exists and the constructor throws the error.
-
-## Conclusion
-
-You made it! You can examine and download the complete source for this final version from the live example.
-
-
-## Frequently asked questions
-
-Now that you understand NgModules, you may be interested
-in the companion [NgModule FAQs](guide/ngmodule-faq "NgModule FAQs") page
-with its ready answers to specific design and implementation questions.
diff --git a/aio/content/guide/ngmodules.md b/aio/content/guide/ngmodules.md
new file mode 100644
index 0000000000..a55aa2e516
--- /dev/null
+++ b/aio/content/guide/ngmodules.md
@@ -0,0 +1,75 @@
+# NgModules
+
+#### Prerequisites
+
+A basic understanding of the following concepts:
+* [Bootstrapping](guide/bootstrapping).
+* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
+
+
+
+**NgModules** configure the injector and the compiler and help organize related things together
+
+An NgModule is a class marked by the `@NgModule` decorator.
+`@NgModule` takes a metadata object that describes how to compile a component's templates and how to create an injector at runtime.
+It identifies the module's own components, directives, and pipes,
+making some of them public, through the `exports` property public, so that external components can use them.
+`@NgModule` can also add service providers to the application dependency injectors.
+
+For an example app showcasing all the techniques that NgModules related pages
+cover, see the . For explanations on the individual techniques, visit the relevant NgModule pages under the NgModules
+section.
+
+
+## Angular modularity
+
+Modules are a great way to organize an application and extend it with capabilities from external libraries.
+
+Angular libraries are NgModules, such as `FormsModule`, `HttpModule`, and `RouterModule`.
+Many third-party libraries are available as NgModules such as
+Material Design,
+Ionic, and
+AngularFire2.
+
+NgModules consolidate components, directives, and pipes into
+cohesive blocks of functionality, each focused on a
+feature area, application business domain, workflow, or common collection of utilities.
+
+Modules can also add services to the application.
+Such services might be internally developed, like something you'd develop yourself or come from outside sources, such as the Angular router and HTTP client.
+
+Modules can be loaded eagerly when the application starts or lazy loaded asynchronously by the router.
+
+NgModule metadata does the following:
+
+* Declares which components, directives, and pipes belong to the module.
+* Makes some of those components, directives, and pipes public so that other module's component templates can use them.
+* Imports other modules with the components, directives, and pipes that components in the current module need.
+* Provides services at the other application components can use.
+
+Every Angular app has at least one module, the root module.
+You [bootstrap](guide/bootstrapping) that module to launch the application.
+
+The root module is all you need in a simple application with a few components.
+As the app grows, you refactor the root module into [feature modules](guide/feature-modules)
+that represent collections of related functionality.
+You then import these modules into the root module.
+
+## The basic NgModule
+
+The CLI generates the following basic app module when creating a new app.
+
+
+
+
+At the top are the import statements. The next section is where you configure the `@NgModule` by stating what components and directives belong to it (`declarations`) as well as which other modules it uses (`imports`). This page builds on [Bootstrapping](guide/bootstrapping), which covers the structure of an NgModule in detail. If you need more information on the structure of an `@NgModule`, be sure to read [Bootstrapping](guide/bootstrapping).
+
+
+
+## More on NgModules
+
+You may also be interested in the following:
+* [Feature Modules](guide/feature-modules).
+* [Entry Components](guide/entry-components).
+* [Providers](guide/providers).
+* [Types of NgModules](guide/module-types).
diff --git a/aio/content/guide/providers.md b/aio/content/guide/providers.md
new file mode 100644
index 0000000000..83315d1ece
--- /dev/null
+++ b/aio/content/guide/providers.md
@@ -0,0 +1,75 @@
+# Providers
+
+#### Prerequisites:
+* A basic understanding of [Bootstrapping](guide/bootstrapping).
+* Familiarity with [Frequently Used Modules](guide/frequent-ngmodules).
+
+For the final sample app using the provider that this page describes,
+see the .
+
+
+
+## Create a service
+You can provide services to your app by using the providers array in an NgModule.
+Consider the default app generated by the CLI. In order to add
+a user service to it,
+you can generate one by entering the following command in the terminal window:
+
+```sh
+ng generate service User
+```
+
+This creates a service called `UserService` and returns a message telling you
+that you need to provide it. Update `app.module.ts` by importing it with your
+other import statements at the top of the file and adding it to the providers array:
+
+
+
+
+
+## Provider scope
+
+When you add a service provider to the providers array of the root module, it’s available throughout the app. Additionally, when you import a module that has providers, those providers are also available to all the classes in the app as long they have the lookup token. For example, if you import the `HttpModule` into your `AppModule`, its providers are then available to the entire app and you can make HTTP requests from anywhere in your app.
+
+
+## Limiting provider scope by lazy loading modules
+
+In the basic CLI generated app, modules are eagerly loaded which means that they are all loaded when the app launches. Angular uses an injector system to make things available between modules. In an eagerly loaded app, the root application injector makes all of the providers in all of the modules available throughout the app.
+
+This behavior necessarily changes when you use lazy loading. Lazy loading is when you load modules only when you need them; for example, when routing. They aren’t loaded right away like with eagerly loaded modules. This means that any services listed in their provider arrays aren’t available because the root injector doesn’t know about these modules.
+
+
+
+When the Angular router lazy-loads a module, it creates a new injector. This injector is a child of the root application injector. Imagine a tree of injectors; there is a single root injector and then a child injector for each lazy loaded module. The router adds all of the providers from the root injector to the child injector. When the router creates a component within the lazy-loaded context, Angular prefers service instances created from these providers to the service instances of the application root injector.
+
+Any component created within a lazy loaded module’s context, such as by router navigation, gets the local instance of the service, not the instance in the root application injector. Components in external modules continue to receive the instance created for the application root.
+
+Though you can provide services by lazy loading modules, not all services can be lazy loaded. For instance, some modules only work in the root module, such as the Router. The Router works with the global location object in the browser.
+
+
+## Limiting provider scope with components
+
+Another way to limit provider scope is by adding the service you want to limit to the component’s provider array. Component providers and NgModule providers are independent of each other. This method is helpful for when you want to eagerly load a module that needs a service all to itself. Providing a service in the component limits the service only to that component (other components in the same module can’t access it.)
+
+
+## Providing services in modules vs. components
+
+Generally, provide services the whole app needs in the root module and scope services by providing them in lazy loaded modules.
+
+The router works at the root level so if you put providers in a component, even `AppComponent`, lazy loaded modules, which rely on the router, can’t see them.
+
+
+Register a provider with a component when you must limit a service instance to a component and its component tree, that is, its child components. For example, a customer editing component, `UserEditorComponent`, that needs a private copy of a caching `UserService` should register the `UserService` with the `UserEditorComponent`. Then each new instance of the `UserEditorComponent` gets its own cached service instance.
+
+
+
+
+## More on NgModules
+
+You may also be interested in:
+* [Singleton Services](guide/singleton-services), which elaborates on the concepts covered on this page.
+* [Lazy Loading Modules](guide/lazy-loading-ngmodules).
+* [NgModule FAQ](guide/ngmodule-faq).
+
+
+
diff --git a/aio/content/guide/router.md b/aio/content/guide/router.md
index 8cf8978a52..a44a541de8 100644
--- a/aio/content/guide/router.md
+++ b/aio/content/guide/router.md
@@ -1274,7 +1274,7 @@ The **Routing Module** has several characteristics:
* Separates routing concerns from other application concerns.
* Provides a module to replace or remove when testing the application.
* Provides a well-known location for routing service providers including guards and resolvers.
-* Does **not** [declare components](guide/ngmodule-faq#routing-module).
+* Does **not** declare components.
{@a routing-refactor}
diff --git a/aio/content/guide/setup.md b/aio/content/guide/setup.md
index e74574166a..f48517fa53 100644
--- a/aio/content/guide/setup.md
+++ b/aio/content/guide/setup.md
@@ -270,7 +270,7 @@ The following are all in `src/`
Compiles the application with the [JIT compiler](guide/glossary#jit) and
- [bootstraps](guide/bootstrapping#main "bootstrap the application")
+ [bootstraps](guide/bootstrapping)
the application's main module (`AppModule`) to run in the browser.
The JIT compiler is a reasonable choice during the development of most projects and
it's the only viable choice for a sample running in a _live-coding_ environment like Plunker.
diff --git a/aio/content/guide/sharing-ngmodules.md b/aio/content/guide/sharing-ngmodules.md
new file mode 100644
index 0000000000..c5e4e6a515
--- /dev/null
+++ b/aio/content/guide/sharing-ngmodules.md
@@ -0,0 +1,76 @@
+# Sharing Modules
+
+#### Prerequisites
+A basic understanding of the following:
+* [Feature Modules](guide/feature-modules).
+* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
+* [Frequently Used Modules](guide/frequent-ngmodules).
+* [Routing and Navigation](guide/router).
+* [Lazy loading modules](guide/lazy-loading-ngmodules).
+
+
+
+
+
+
+Creating shared modules allows you to organize and streamline your code. You can put commonly
+used directives, pipes, and components into one module and then import just that module wherever
+you need it in other parts of your app.
+
+Consider the following module from an imaginary app:
+
+
+```typescript
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { FormsModule } from '@angular/forms';
+import { OrdersPipe } from './orders.pipe';
+import { NewItemDirective } from './newitem.directive';
+@NgModule({
+ imports: [ CommonModule ],
+ declarations: [ OrdersPipe, NewItemDirective ],
+ exports: [ OrdersPipe, NewItemDirective,
+ CommonModule, FormsModule ]
+})
+export class SharedModule { }
+```
+
+Note the following:
+
+* It imports the `CommonModule` because the module's component needs common directives.
+* It declares and exports the utility pipe, directive, and component classes.
+* It re-exports the `CommonModule` and `FormsModule`.
+
+By re-exporting `CommonModule` and `FormsModule`, any other module that imports this
+`SharedModule`, gets access to directives like `NgIf` and `NgFor` from `CommonModule`
+and can bind to component properties with `[(ngModel)]`, a directive in the `FormsModule`.
+
+Even though the components declared by `SharedModule` might not bind
+with `[(ngModel)]` and there may be no need for `SharedModule`
+to import `FormsModule`, `SharedModule` can still export
+`FormsModule` without listing it among its `imports`. This
+way, you can give other modules access to `FormsModule` without
+having to import it directly into the `@NgModule` decorator.
+
+### Using components vs services from other modules.
+
+There is an important distinction between using another module's component and
+using a service from another module.. Import modules when you want to use
+directives, pipes, and components. Importing a module with services means that you will have a new instance of that service, which typically is not what you need, (typically one wants to reuse an existing service.) Use module imports to control service instantiation.
+
+The most common way to get a hold of sharedservices is through Angular
+[dependency injection](guide/dependency-injection), rather than through the module system (importing a module will result in a new service instance, which is not a typical usage).
+
+To read about sharing services, see [Providers](guide/providers).
+
+
+
+
+## More on NgModules
+
+You may also be interested in the following:
+* [Providers](guide/providers).
+* [Types of Modules](guide/module-types).
+
+
+
diff --git a/aio/content/guide/singleton-services.md b/aio/content/guide/singleton-services.md
new file mode 100644
index 0000000000..ea19f9c777
--- /dev/null
+++ b/aio/content/guide/singleton-services.md
@@ -0,0 +1,179 @@
+# Singleton services
+
+#### Prerequisites:
+
+* A basic understanding of [Bootstrapping](guide/bootstrapping).
+* Familiarity with [Providers](guide/providers).
+
+For a sample app using the app-wide singleton service
+that this page describes, see the
+live example
+showcasing all the documented features of NgModules.
+
+
+
+## Providing a singleton service
+
+An injector created from a module definition will have services which are singletons with respect to that injector. To control the lifetime of services, one controls the creation and destruction of injectors. For example, a route will have an associated module. When the route is activated, an injector is created from that module as a child of the current injector. When you navigate away from the route, the injector is destroyed. This means that services declared in a route module will have a lifetime equal to that of the route. Similarly, services provided in an application module will have the same lifetime of the application, hence singleton.
+
+The following example module is called, as a convention, `CoreModule`. This use of `@NgModule` creates organizational infrastructure and gives you
+a way of providing services from a designated NgModule.
+
+
+
+
+Here, `CoreModule` provides the `UserService`, and because `AppModule`
+imports `CoreModule`, any services that `CoreModule` provides are available
+throughout the app, because it is a root of the injector tree. It will also be a singleton because the injector lifetime of the `AppModule` is for the duration of the application.
+
+Angular registers the `UserService` provider with the app root
+injector, making a singleton instance of the `UserService`
+available to any component that needs it,
+whether that component is eagerly or lazily loaded.
+
+The root `AppModule` could register the `UserService` directly,
+but as the app grows, it could have other services and
+components like spinners, modals, and so on. To
+keep your app organized, consider using a module such as `CoreModule`.
+This technique simplifies the root `AppModule` in its
+capacity as orchestrator of the application as a whole.
+
+Now you can inject such services into components as needed. In terms of
+Angular NgModules, you only need to define the services in one `@NgModule`.
+See [JS Modules vs. NgModules](guide/ngmodule-vs-jsmodule) for
+more information on how to differentiate between the two.
+
+As a general rule, import modules with providers _exactly once_,
+preferably in the application's _root module_.
+That's also usually the best place to configure, wrap, and override them.
+
+For more detailed information on services, see
+[part 5](tutorial/toh-pt4) of the [Tour of Heroes tutorial](tutorial).
+
+
+## `forRoot()`
+
+If a module provides both providers and declarations (components, directives, pipes) then loading it in a child injector such as a route, would duplicate the provider instances. The duplication of providers would cause issues as they would shadow the root instances, which are probably meant to be singletons. For this reason Angular provides a way to separate providers out of the module so that same module can be imported into the root module with `providers` and child modules without `providers`.
+
+1. Create a static method `forRoot()` (by convention) on the module.
+2. Place the providers into the `forRoot` method as follows.
+
+
+
+To make this more concrete, consider the `RouterModule` as an example. `RouterModule` needs to provide the `Router` service, as well as the `RouterOutlet` directive. `RouterModule` has to be imported by the root application module so that the application has a `Router` and the application has at least one `RouterOutlet`. It also must be imported by the individual route components so that they can place `RouterOutlet` directives into their template for sub-routes.
+
+If the `RouterModule` didn’t have `forRoot()` then each route component would instantiate a new `Router` instance, which would break the application as there can only be one `Router`. For this reason, the `RouterModule` has the `RouterOutlet` declaration so that it is available everywhere, but the `Router` provider is only in the `forRoot()`. The result is that the root application module imports `RouterModule.forRoot(...)` and gets a `Router`, whereas all route components import `RouterModule` which does not include the `Router`.
+
+If you have a module which provides both providers and declarations, use this pattern to separate them out.
+
+A module that adds providers to the application can offer a
+facility for configuring those providers as well through the
+`forRoot()` method.
+
+`forRoot()` takes a service configuration object and returns a
+[ModuleWithProviders](api/core/ModuleWithProviders), which is
+a simple object with the following properties:
+
+* `ngModule`: in this example, the `CoreModule` class.
+* `providers`: the configured providers.
+
+In the live example
+the root `AppModule` imports the `CoreModule` and adds the
+`providers` to the `AppModule` providers. Specifically,
+Angular accumulates all imported providers
+before appending the items listed in `@NgModule.providers`.
+This sequence ensures that whatever you add explicitly to
+the `AppModule` providers takes precedence over the providers
+of imported modules.
+
+Import `CoreModule` and use its `forRoot()` method one time, in `AppModule`, because it registers services and you only want to register those services one time in your app. If you were to register them more than once, you could end up with multiple instances of the service and a runtime error.
+
+You can also add a `forRoot()` method in the `CoreModule` that configures
+the core `UserService`.
+
+In the following example, the optional, injected `UserServiceConfig`
+extends the core `UserService`. If a `UserServiceConfig` exists, the `UserService` sets the user name from that config.
+
+
+
+
+
+Here's `forRoot()` that takes a `UserServiceConfig` object:
+
+
+
+
+
+Lastly, call it within the `imports` list of the `AppModule`.
+
+
+
+
+
+The app displays "Miss Marple" as the user instead of the default "Sherlock Holmes".
+
+Remember to _import_ `CoreModule` as a Javascript import at the top of the file; don't add it to more than one `@NgModule` `imports` list.
+
+
+
+## Prevent reimport of the `CoreModule`
+
+Only the root `AppModule` should import the `CoreModule`. If a
+lazy-loaded module imports it too, the app can generate
+[multiple instances](guide/ngmodule-faq#q-why-bad) of a service.
+
+To guard against a lazy-loaded module re-importing `CoreModule`, add the following `CoreModule` constructor.
+
+
+
+
+
+The constructor tells Angular to inject the `CoreModule` into itself.
+The injection would be circular if Angular looked for
+`CoreModule` in the _current_ injector. The `@SkipSelf`
+decorator means "look for `CoreModule` in an ancestor
+injector, above me in the injector hierarchy."
+
+If the constructor executes as intended in the `AppModule`,
+there would be no ancestor injector that could provide an instance of `CoreModule` and the injector should give up.
+
+By default, the injector throws an error when it can't
+find a requested provider.
+The `@Optional` decorator means not finding the service is OK.
+The injector returns `null`, the `parentModule` parameter is null,
+and the constructor concludes uneventfully.
+
+It's a different story if you improperly import `CoreModule` into a lazy-loaded module such as `CustomersModule`.
+
+Angular creates a lazy-loaded module with its own injector,
+a _child_ of the root injector.
+`@SkipSelf` causes Angular to look for a `CoreModule` in the parent injector, which this time is the root injector.
+Of course it finds the instance imported by the root `AppModule`.
+Now `parentModule` exists and the constructor throws the error.
+
+Here are the two files in their entirety for reference:
+
+
+
+
+
+
+
+
+
+
+
+## More on NgModules
+
+You may also be interested in:
+* [Sharing NgModules](guide/singleton-services), which elaborates on the concepts covered on this page.
+* [Lazy Loading Modules](guide/lazy-loading-ngmodules).
+* [NgModule FAQ](guide/ngmodule-faq).
+
+
+
diff --git a/aio/content/guide/testing.md b/aio/content/guide/testing.md
index cbdc075c1d..97eb5c1bbb 100644
--- a/aio/content/guide/testing.md
+++ b/aio/content/guide/testing.md
@@ -415,7 +415,7 @@ and re-attach it to a dynamically-constructed Angular test module
tailored specifically for this battery of tests.
The `configureTestingModule` method takes an `@NgModule`-like metadata object.
-The metadata object can have most of the properties of a normal [NgModule](guide/ngmodule).
+The metadata object can have most of the properties of a normal [NgModule](guide/ngmodules).
_This metadata object_ simply declares the component to test, `BannerComponent`.
The metadata lack `imports` because (a) the default testing module configuration already has what `BannerComponent` needs
@@ -1782,7 +1782,7 @@ It's a bit tighter and smaller, with fewer import statements (not shown).
### Import the feature module
-The `HeroDetailComponent` is part of the `HeroModule` [Feature Module](guide/ngmodule#feature-modules) that aggregates more of the interdependent pieces
+The `HeroDetailComponent` is part of the `HeroModule` [Feature Module](guide/feature-modules) that aggregates more of the interdependent pieces
including the `SharedModule`.
Try a test configuration that imports the `HeroModule` like this one:
diff --git a/aio/content/guide/upgrade.md b/aio/content/guide/upgrade.md
index 433e1f13b4..6a1b6c7688 100644
--- a/aio/content/guide/upgrade.md
+++ b/aio/content/guide/upgrade.md
@@ -387,7 +387,7 @@ bootstrapping the AngularJS module.
-Read more about [NgModules](guide/ngmodule).
+For more information, see [NgModules](guide/ngmodules).
diff --git a/aio/content/images/guide/feature-modules/feature-module.png b/aio/content/images/guide/feature-modules/feature-module.png
new file mode 100644
index 0000000000..9faec0e71d
Binary files /dev/null and b/aio/content/images/guide/feature-modules/feature-module.png differ
diff --git a/aio/content/images/guide/frequent-ngmodules/browser-module-error.gif b/aio/content/images/guide/frequent-ngmodules/browser-module-error.gif
new file mode 100644
index 0000000000..f84dc08164
Binary files /dev/null and b/aio/content/images/guide/frequent-ngmodules/browser-module-error.gif differ
diff --git a/aio/content/images/guide/lazy-loading-ngmodules/chunk-arrow.png b/aio/content/images/guide/lazy-loading-ngmodules/chunk-arrow.png
new file mode 100644
index 0000000000..d42dd1f6f4
Binary files /dev/null and b/aio/content/images/guide/lazy-loading-ngmodules/chunk-arrow.png differ
diff --git a/aio/content/images/guide/lazy-loading-ngmodules/chunk.png b/aio/content/images/guide/lazy-loading-ngmodules/chunk.png
new file mode 100644
index 0000000000..f35bca8e0f
Binary files /dev/null and b/aio/content/images/guide/lazy-loading-ngmodules/chunk.png differ
diff --git a/aio/content/images/guide/lazy-loading-ngmodules/clear.gif b/aio/content/images/guide/lazy-loading-ngmodules/clear.gif
new file mode 100644
index 0000000000..6aacf02f8c
Binary files /dev/null and b/aio/content/images/guide/lazy-loading-ngmodules/clear.gif differ
diff --git a/aio/content/images/guide/lazy-loading-ngmodules/clear.png b/aio/content/images/guide/lazy-loading-ngmodules/clear.png
new file mode 100644
index 0000000000..70379ce1f8
Binary files /dev/null and b/aio/content/images/guide/lazy-loading-ngmodules/clear.png differ
diff --git a/aio/content/images/guide/lazy-loading-ngmodules/lazy-load-relationship.jpg b/aio/content/images/guide/lazy-loading-ngmodules/lazy-load-relationship.jpg
new file mode 100644
index 0000000000..3aa0004925
Binary files /dev/null and b/aio/content/images/guide/lazy-loading-ngmodules/lazy-load-relationship.jpg differ
diff --git a/aio/content/images/guide/lazy-loading-ngmodules/network-tab.png b/aio/content/images/guide/lazy-loading-ngmodules/network-tab.png
new file mode 100644
index 0000000000..29b13a9d87
Binary files /dev/null and b/aio/content/images/guide/lazy-loading-ngmodules/network-tab.png differ
diff --git a/aio/content/images/guide/lazy-loading-ngmodules/three-buttons.png b/aio/content/images/guide/lazy-loading-ngmodules/three-buttons.png
new file mode 100644
index 0000000000..b44b0a8265
Binary files /dev/null and b/aio/content/images/guide/lazy-loading-ngmodules/three-buttons.png differ
diff --git a/aio/content/navigation.json b/aio/content/navigation.json
index 6787543750..00944edb07 100644
--- a/aio/content/navigation.json
+++ b/aio/content/navigation.json
@@ -74,6 +74,7 @@
},
{
+ "url": "tutorial",
"title": "Tutorial",
"tooltip": "The Tour of Heroes tutorial takes you through the steps of creating an Angular application in TypeScript.",
"children": [
@@ -121,6 +122,7 @@
},
{
+ "url": "guide/architecture",
"title": "Fundamentals",
"tooltip": "The fundamentals of Angular",
"children": [
@@ -168,11 +170,6 @@
"title": "Attribute Directives",
"tooltip": "Attribute directives attach behavior to elements."
},
- {
- "url": "guide/structural-directives",
- "title": "Structural Directives",
- "tooltip": "Structural directives manipulate the layout of the page."
- },
{
"url": "guide/pipes",
"title": "Pipes",
@@ -216,21 +213,70 @@
}
]
},
-
{
"url": "guide/bootstrapping",
"title": "Bootstrapping",
"tooltip": "Tell Angular how to construct and bootstrap the app in the root \"AppModule\"."
},
-
{
+
"title": "NgModules",
- "tooltip": "Modularize your app with NgModules.",
+ "tooltip": "NgModules.",
"children": [
{
- "url": "guide/ngmodule",
- "title": "NgModules",
- "tooltip": "Define application modules with the NgModule."
+ "url": "guide/ngmodules",
+ "title": "NgModules Introduction",
+ "tooltip": "Use NgModules to make your apps efficient."
+ },
+ {
+ "url": "guide/ngmodule-vs-jsmodule",
+ "title": "JS Modules vs NgModules",
+ "tooltip": "Differentiate between JavaScript modules and NgModules."
+ },
+ {
+ "url": "guide/frequent-ngmodules",
+ "title": "Frequently Used NgModules",
+ "tooltip": "Introduction to the most frequently used NgModules."
+ },
+ {
+ "url": "guide/module-types",
+ "title": "Types of NgModules",
+ "tooltip": "Description of the different types of feature module."
+ },
+ {
+ "url": "guide/entry-components",
+ "title": "Entry Components",
+ "tooltip": "All about entry components in Angular."
+ },
+ {
+ "url": "guide/feature-modules",
+ "title": "Feature Modules",
+ "tooltip": "Create feature modules to organize your code."
+ },
+ {
+ "url": "guide/providers",
+ "title": "Providers",
+ "tooltip": "Providers and NgModules."
+ },
+ {
+ "url": "guide/singleton-services",
+ "title": "Singleton Services",
+ "tooltip": "Creating singleton services."
+ },
+ {
+ "url": "guide/lazy-loading-ngmodules",
+ "title": "Lazy Loading Feature Modules",
+ "tooltip": "Lazy load modules to speed up your apps."
+ },
+ {
+ "url": "guide/sharing-ngmodules",
+ "title": "Sharing NgModules",
+ "tooltip": "Share NgModules to streamline your apps."
+ },
+ {
+ "url": "guide/ngmodule-api",
+ "title": "NgModule API",
+ "tooltip": "Understand the details of NgModules."
},
{
"url": "guide/ngmodule-faq",
diff --git a/aio/content/tutorial/toh-pt1.md b/aio/content/tutorial/toh-pt1.md
index a5b0d76536..e59e918ffe 100644
--- a/aio/content/tutorial/toh-pt1.md
+++ b/aio/content/tutorial/toh-pt1.md
@@ -173,7 +173,7 @@ and what other files and libraries the app requires.
This information is called _metadata_
Some of the metadata is in the `@Component` decorators that you added to your component classes.
-Other critical metadata is in [`@NgModule`](guide/ngmodule) decorators.
+Other critical metadata is in [`@NgModule`](guide/ngmodules) decorators.
The most important `@NgModule`decorator annotates the top-level **AppModule** class.
@@ -198,7 +198,7 @@ When the browser refreshes, the app should work again. You can edit the hero's n
### Declare _HeroesComponent_
-Every component must be declared in _exactly one_ [NgModule](guide/ngmodule).
+Every component must be declared in _exactly one_ [NgModule](guide/ngmodules).
_You_ didn't declare the `HeroesComponent`.
So why did the application work?
diff --git a/aio/content/tutorial/toh-pt4.md b/aio/content/tutorial/toh-pt4.md
index 64de5949bb..807f886f31 100644
--- a/aio/content/tutorial/toh-pt4.md
+++ b/aio/content/tutorial/toh-pt4.md
@@ -107,7 +107,7 @@ The `HeroService` is now ready to plug into the `HeroesComponent`.
- Learn more about _providers_ in the [NgModules](guide/ngmodule#providers) guide.
+ Learn more about _providers_ in the [Providers](guide/providers) guide.
@@ -232,11 +232,11 @@ Find the `getHeroes` method and replace it with the following code
-
-
diff --git a/aio/yarn.lock b/aio/yarn.lock
index b45153cbd0..48570242c5 100644
--- a/aio/yarn.lock
+++ b/aio/yarn.lock
@@ -2186,6 +2186,12 @@ debug@2.6.8:
dependencies:
ms "2.0.0"
+debug@2.6.8, debug@^2.6.8:
+ version "2.6.8"
+ resolved "https://registry.yarnpkg.com/debug/-/debug-2.6.8.tgz#e731531ca2ede27d188222427da17821d68ff4fc"
+ dependencies:
+ ms "2.0.0"
+
decamelize@^1.0.0, decamelize@^1.1.1, decamelize@^1.1.2:
version "1.2.0"
resolved "https://registry.yarnpkg.com/decamelize/-/decamelize-1.2.0.tgz#f6534d15148269b20352e7bee26f501f9a191290"
+
+
+
+
+
+
+