angular-cn/public/docs/ts/latest/guide/appmodule.jade

include ../_util-fns

:marked
  An Angular module 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 it anything you want. The conventional name is `AppModule`.

  The [setup](setup.html) instructions produce a new project with the following minimal `AppModule`.
  You'll evolve this module as your application grows.

+makeExample('setup/ts/app/app.module.ts','', 'app/app.module.ts')(format='.')

:marked
  After the `import` statements, you come to a class adorned with the
  **`@NgModule`** [_decorator_](glossary.html#decorator '"Decorator" explained').

  The `@NgModule` decorator identifies `AppModule` as an Angular module class (also called an `NgModule` class).
  `@NgModule` takes a _metadata_ object that tells Angular how to compile and launch the application.

  * **_imports_** — the `BrowserModule` that this and every application needs to run in a browser.
  * **_declarations_** — the application's lone component, which is also ...
  * **_bootstrap_** — the _root_ component that Angular creates and inserts into the `index.html` host web page.
 
  The [Angular Modules (NgModules)](ngmodule.html) guide dives deeply into the details of Angular modules.
  All you need to know at the moment is a few basics about these three properties.  

a#imports
:marked
  ### 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 `HttpModule`. The router is in the `RouterModule`.
  Eventually you may create a feature module.

  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 and cookbook pages will tell you when you need to add additional modules to this array.

.alert.is-important
   :marked
     **Only `NgModule` classes** go in the `imports` array. Don't put any other kind of class in `imports`.

.l-sub-section
  :marked
    Don't confuse the `import` statements at the top of the file with the Angular module's `imports` array.
    They have different jobs.

    The _JavaScript_ `import` statements give you access to symbols _exported_ by other files
    so you can reference them within _this_ file. 
    They have nothing to do with Angular and Angular knows nothing about them.

    The _module's_ `imports` array tells Angular about specific Angular modules — classes decorated with `@NgModule` —
    that the application needs to function properly.
a#declarations
:marked
  ### The _declarations_ array
  
  You must declare _every_ component in one (and _only one_) `NgModule` class.
  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'll learn to create two other kinds of classes — 
  [directives](attribute-directives.html) and [pipes](pipes.html) —
  that you must also add to the `declarations` array.

.alert.is-important
   :marked
      **Only _declarables_** — _components_, _directives_ and _pipes_ — belong in the `declarations` array.  
      Don't put any other kind of class in `declarations`; _not_ `NgModule` classes, _not_ service classes, _not_ model classes.

a#bootstrap-array
:marked
  ### The _bootstrap_ 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
  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.

  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.

  You can call the one _root_ component anything you want but most developers call it `AppComponent`.

  Which brings us to the _bootstrapping_ process itself.

a#main
l-main-section
:marked
  ## Bootstrap in _main.ts_

  There are many ways to bootstrap an application.
  The variations depend upon how you want to compile the application and where you want to run it.
  
  In the beginning, you will compile the application dynamically with the _Just-in-Time (JIT)_ compiler
  and you'll run it in a browser. You can learn about other options later.

  The recommended place to bootstrap a JIT-compiled browser application is in a separate file 
  in the `app` folder named `app/main.ts`
+makeExample('setup/ts/app/main.ts','','app/main.ts')(format='.')
:marked
  This code creates a browser platform for dynamic (JIT) 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 `my-app` 
  so Angular looks for a `<my-app>` tag in the `index.html` like this one ...
+makeExample('setup/ts/index.html','my-app')(format='.')
:marked
  ... and displays the `AppComponent` there.

  This file is very stable. Once you've set it up, you may never change it again.

a#quickstart-appmodule
l-main-section
:marked
  ## QuickStart's _AppModule_
  Every Angular application must have a root `NgModule`, even the [QuickStart](../quickstart.html).
  You didn't see it but it was there.

  A script in the `index.html` generated a hidden `AppModule` and bootstrapped it for you
  so you could focus on the `AppComponent` and discover the _essential Angular_ more quickly.

  If you're feeling adventurous, add your own `AppModule` and `main.ts` to the
  live code in the _QuickStart_ plunker.

  Remove the following `<script>` tag from the `index.html` and see _your_ work in action.
+makeExample('quickstart/ts/index.html','autobootstrap','Remove this script tag from "index.html"')(format='.')