|
| 1 | +include ../_util-fns |
| 2 | + |
| 3 | +:marked |
| 4 | + # Angular Modules (NgModules) have landed in Angular RC5! |
| 5 | + |
| 6 | + _Angular Modules_, also known as _NgModules_, are the powerful new way to organize and bootstrap your Angular application. |
| 7 | +.l-sub-section |
| 8 | + :marked |
| 9 | + Read more in the ["RC5 and NgModules" announcement](https://angularjs.blogspot.com). |
| 10 | + |
| 11 | + Learn the details of NgModule in the [Angular Module](../guide/ngmodule) chapter. |
| 12 | +:marked |
| 13 | + The new `@NgModule` decorator gives you module-level components, directives, and pipes without |
| 14 | + the need to specify them repeatedly in every component of your application. |
| 15 | + |
| 16 | + The `@NgModule` metadata give the Angular compiler the context needed so that you can use the same code |
| 17 | + regardless of whether you are running Angular in [Ahead of Time](../glossary.html#aot) or [Just in Time](../glossary.html#jit) mode. |
| 18 | + |
| 19 | + ## How do I use them? |
| 20 | + |
| 21 | + If you were previously writing an Angular application, your app should continue to work in RC5. |
| 22 | + We’ve worked hard to ensure that applications that worked with RC4 continue to work while you migrate. |
| 23 | + For this to work, we’re doing 2 things automatically for you: |
| 24 | + |
| 25 | + * We create an implicit `NgModule` for you as part of the `bootstrap()` command |
| 26 | + * We automatically hoist your components, pipes, and directives |
| 27 | + |
| 28 | + While your application will continue to work today, |
| 29 | + it’s important that you update your application to ensure future updates and deprecations don’t negatively affect you. |
| 30 | + To make it easier, you can think of the process as having 5 steps. |
| 31 | + |
| 32 | + 1. **Update to RC5** - Your application should continue to work without modification, but it’s important that you are running the latest version of Angular. |
| 33 | + |
| 34 | + 2. **Create an _NgModule_** - Create the root `NgModule` that you’ll use to bootstrap your application. |
| 35 | + |
| 36 | + 3. **Update your bootstrap** - Bootstrap that module instead of your root component |
| 37 | + |
| 38 | + 4. **Update your 3rd party libraries** - Take advantage of the latest from Forms, Material, Http, and more |
| 39 | + |
| 40 | + 5. **Cleanup** - Clean up your code. |
| 41 | + The deprecated classes, methods and properties will be removed from Angular very soon. |
| 42 | + |
| 43 | + Prefer to look at code and diffs? |
| 44 | + Check out the upgrade in [one commit](https://github.com/StephenFluin/ngmodule-migration/commit/9f9c6ae099346e491fc31d77bf65ed440e1f164c). |
| 45 | + |
| 46 | + ## 1. Update to RC5 |
| 47 | + If you use npm, you should be able to either update your package.json file and run npm install. |
| 48 | + Or alternatively you can run the following command: |
| 49 | + |
| 50 | + ```bash |
| 51 | + npm install @angular/{core,common,compiler,angular-cli,platform-browser,platform-browser-dynamic}@2.0.0-rc.5 --save |
| 52 | + ``` |
| 53 | + |
| 54 | + You should also update any libraries you are using |
| 55 | + |
| 56 | + ```bash |
| 57 | + npm install @angular/router@3.0.0-rc.1 |
| 58 | + npm install @angular/forms@1.0.0-rc.1 |
| 59 | + npm install @angular2-material/{button,card,toolbar,etc}@experimental |
| 60 | + ``` |
| 61 | + |
| 62 | + ## 2. Create an NgModule |
| 63 | + Create a new file called app.module.ts. Populate it with your root component as follows: |
| 64 | + |
| 65 | + ```javascript |
| 66 | + import { NgModule } from '@angular/core'; |
| 67 | + import { BrowserModule } from '@angular/platform-browser'; |
| 68 | + import { AppComponent } from './app.component'; |
| 69 | + |
| 70 | + @NgModule({ |
| 71 | + declarations: [AppComponent], |
| 72 | + imports: [BrowserModule], |
| 73 | + bootstrap: [AppComponent], |
| 74 | + }) |
| 75 | + export class AppModule {} |
| 76 | + ``` |
| 77 | + |
| 78 | + |
| 79 | + ## 3. Update your bootstrap |
| 80 | + Update your `main.ts` file to bootstrap using the Just in Time compiler. |
| 81 | + |
| 82 | + ```javascript |
| 83 | + import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; |
| 84 | + import { AppModule } from './app/app.module'; |
| 85 | + |
| 86 | + platformBrowserDynamic().bootstrapModule(AppModule); |
| 87 | + ``` |
| 88 | + |
| 89 | + ## 4. Update your 3rd party libraries |
| 90 | + Remove any 3rd party libraries from you AppComponent’s providers. |
| 91 | + You’ll want to move these to your NgModule’s imports, while updating to use each library’s provided Module(s). |
| 92 | + |
| 93 | + ```javascript |
| 94 | + imports: [ |
| 95 | + BrowserModule, |
| 96 | + // Router |
| 97 | + RouterModule.forRoot(config), |
| 98 | + // Forms |
| 99 | + FormsModule, |
| 100 | + // Material Design |
| 101 | + MdSlideToggleModule, |
| 102 | + MdButtonModule, |
| 103 | + MdToolbarModule, |
| 104 | + MdCardModule, |
| 105 | + MdInputModule, |
| 106 | + ], |
| 107 | + ``` |
| 108 | + |
| 109 | + ## 5. Cleanup |
| 110 | + As of RC5, we allow you to leave `directives` and `pipes` in your `@Component` decorators. |
| 111 | + In fact, we automatically hoist (add) them to the NgModule that they belong to. |
| 112 | + |
| 113 | +.alert.is-important |
| 114 | + :marked |
| 115 | + This behavior is provided temporarily for backward compatibility. It will soon be removed. |
| 116 | + |
| 117 | + Stay ahead of this deprecation by removing them from your components and placing them into your `NgModule` declarations |
| 118 | + as soon as possible. |
| 119 | +:marked |
0 commit comments