include ../_util-fns

:marked
  # Angular Modules (NgModules) have landed in Angular RC5!

  _Angular Modules_, also known as _NgModules_, are the powerful new way to organize and bootstrap your Angular application. 
.l-sub-section
  :marked
    Read more in the ["RC5 and NgModules" announcement](https://angularjs.blogspot.com).

    Learn the details of NgModule in the [Angular Module](../guide/ngmodule.html) chapter.
:marked
  The new  `@NgModule` decorator gives you module-level components, directives, and pipes without 
  the need to specify them repeatedly in every component of your application. 
  
  The `@NgModule` metadata give the Angular compiler the context needed so that you can use the same code 
  regardless of whether you are running Angular in [Ahead-of-time](../glossary.html#aot) or [Just
   in Time](../glossary.html#jit) mode.

  ## How do I use them?

  If you were previously writing an Angular application, your app should continue to work in RC5. 
  We’ve worked hard to ensure that applications that worked with RC4 continue to work while you migrate. 
  For this to work, we’re doing 2 things automatically for you:

  * We create an implicit `NgModule` for you as part of the `bootstrap()` command
  * We automatically hoist your components, pipes, and directives

  While your application will continue to work today, 
  it’s important that you update your application to ensure future updates and deprecations don’t negatively affect you. 
  To make it easier, you can think of the process as having 5 steps.

  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.
  
  2. **Create an _NgModule_** - Create the root `NgModule` that you’ll use to bootstrap your application.
  
  3. **Update your bootstrap** - Bootstrap that module instead of your root component
  
  4. **Update your 3rd party libraries** - Take advantage of the latest from Forms, Material, Http, and more
  
  5. **Cleanup** - Clean up your code. 
  The deprecated classes, methods and properties will be removed from Angular very soon.

  Prefer to look at code and diffs? 
  Check out the upgrade in [one commit](https://github.com/StephenFluin/ngmodule-migration/commit/9f9c6ae099346e491fc31d77bf65ed440e1f164c).

  ## 1. Update to RC5
  If you use npm, you should be able to either update your `package.json` file and run `npm install`. 
  Or alternatively you can run the following command:

code-example(format='.' language='bash').
  npm install @angular/{core,common,compiler,platform-browser,platform-browser-dynamic} --save

:marked
  Update your optional libraries

code-example(format='.' language='bash').
  npm install @angular/router
  npm install @angular/forms
  npm install @angular2-material/{core,button,card,...}@latest

:marked
  Update the Angular CLI if you're using that tool

code-example(format='.'  language='bash').
  npm install angular-cli @angular/tsc-wrapped --save-dev

:marked
  ## 2. Create an _NgModule_
  Create a new file called app.module.ts. Populate it with your root component as follows:

code-example(format='.' language='javascript').
  import { NgModule }       from '@angular/core';
  import { BrowserModule  } from '@angular/platform-browser';
  import { AppComponent }   from './app.component';

  @NgModule({
      declarations: [AppComponent],
      imports:      [BrowserModule],
      bootstrap:    [AppComponent],
  })
  export class AppModule {}

:marked
  ## 3. Update your bootstrap
  Update your `main.ts` file to bootstrap using the "Just-in-time" (JiT) compiler.

code-example(format='.' language='javascript').
  import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
  import { AppModule }              from './app/app.module';

  platformBrowserDynamic().bootstrapModule(AppModule);

:marked
  ## 4. Import library modules in your _NgModule_
  Remove the Angular and 3rd party library providers from your `AppComponent` providers 
  and switch to `NgModule` imports as seen in this example.

code-example(format='.' language='javascript').
  imports: [
      BrowserModule, 
      // Router
      RouterModule.forRoot(config), 
      // Forms
      FormsModule, 
      // Material Design
      MdSlideToggleModule, 
      MdButtonModule, 
      MdToolbarModule, 
      MdCardModule, 
      MdInputModule,
  ],

:marked
  ## 5. Cleanup
  For RC5, you can leave your components, directives and pipes 
  in the `directives` and `pipes` properties of your `@Component` metadata.
  In fact, we automatically hoist (add) them to the NgModule to which they belong.

.alert.is-important
  :marked
    This option is temporary for backward compatibility. 
    It will be removed in the final release of Angular 2.0.

    Get ahead of the game and start moving your component `directives` and `pipes` 
    into module `declarations` as soon as possible.
    We intend to delete _all_ deprecated class, methods, and properties in the next RC.
