angular-cn/aio/content/guide/appmodule.md

@title AppModule: the root module

@intro Tell Angular how to construct and bootstrap the app in the root "AppModule".

@description

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 to launch the application. You can call it anything you want. The conventional name is AppModule.

The setup instructions produce a new project with the following minimal AppModule. You'll evolve this module as your application grows.

After the import statements, you come to a class adorned with the @NgModule decorator.

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 (NgModule) 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}

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.

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 Angular module'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 declarations}

The declarations array

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 an NgModule class. If you use a component without declaring it, you'll see a clear error message in the browser console.

You'll learn to create two other kinds of classes — directives and pipes — that you must also add to the declarations array.

Only declarables — components, directives and pipes — belong in the declarations array. Do not put any other kind of class in declarations; not NgModule classes, not service classes, not model classes.

{@a bootstrap-array}

The bootstrap array

You launch the application by bootstrapping 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}

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 src folder named src/main.ts

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 ...

... and displays the AppComponent there.

This 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.

When you're ready to explore these possibilities, visit the Angular Modules (NgModule) guide.