Patrice Chalin
Kathy Walrath
parent
19d06061c5
commit
2ca6d6567b
|
|
@ -1,4 +1,4 @@
|
||||||
extends ../../ts/latest/quickstart.jade
|
extends ../../ts/_cache/quickstart.jade
|
||||||
|
|
||||||
block includes
|
block includes
|
||||||
include _util-fns
|
include _util-fns
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,636 @@
|
||||||
|
block includes
|
||||||
|
include _util-fns
|
||||||
|
- var _Install = 'Install'
|
||||||
|
- var _prereq = 'Node.js'
|
||||||
|
- var _angular_browser_uri = '@angular/platform-browser-dynamic'
|
||||||
|
- var _angular_core_uri = '@angular/core'
|
||||||
|
- var _stepInit = 4 // Step # after NgModule step
|
||||||
|
- var _quickstartSrcURL='https://github.com/angular/quickstart/blob/master/README.md'
|
||||||
|
|
||||||
|
//- TS/Dart shared step counter
|
||||||
|
- var step = _stepInit
|
||||||
|
|
||||||
|
:marked
|
||||||
|
Our QuickStart goal is to build and run a super-simple
|
||||||
|
Angular 2 application in #{_Lang}, and
|
||||||
|
establish a development environment for the remaining documentation samples
|
||||||
|
that also can be the foundation for real world applications.
|
||||||
|
|
||||||
|
.callout.is-helpful
|
||||||
|
header Don't want #{_Lang}?
|
||||||
|
p.
|
||||||
|
Although we're getting started in #{_Lang}, you can also write Angular 2 apps
|
||||||
|
in #{_docsFor == 'ts' ? 'Dart' : 'TypeScript'} and JavaScript.
|
||||||
|
Just select either of those languages from the combo-box in the banner.
|
||||||
|
|
||||||
|
:marked
|
||||||
|
# Try it!
|
||||||
|
|
||||||
|
Try the <live-example></live-example> which loads the sample app
|
||||||
|
<span if-docs="ts">
|
||||||
|
in <a href="http://plnkr.co/" title="Plunker" target="_blank">plunker</a>
|
||||||
|
</span>
|
||||||
|
and displays the simple message:
|
||||||
|
|
||||||
|
figure.image-display
|
||||||
|
img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app")
|
||||||
|
|
||||||
|
:marked
|
||||||
|
# Build this app!
|
||||||
|
|
||||||
|
- [Prerequisite](#prereq): Install #{_prereq}
|
||||||
|
- [Step 1](#create-and-configure): Create the app’s project folder and
|
||||||
|
define package dependencies and special project setup
|
||||||
|
- [Step 2](#root-component): Create the app’s Angular root component
|
||||||
|
<li if-docs="ts">[Step 3](#ngmodule): Create an Angular Module</li>
|
||||||
|
- [Step !{step++}](#main): Add <span ngio-ex>main.ts</span>, identifying the root component to Angular
|
||||||
|
- [Step !{step++}](#index): Add `index.html`, the web page that hosts the application
|
||||||
|
- [Step !{step++}](#build-and-run): Build and run the app
|
||||||
|
- [Make some changes to the app](#make-some-changes)
|
||||||
|
- [Wrap up](#wrap-up)
|
||||||
|
|
||||||
|
- var step = _stepInit // reinitialize step counter for headers to come
|
||||||
|
.l-main-section#prereq
|
||||||
|
h2 Prerequisite: #{_prereq}
|
||||||
|
|
||||||
|
block setup-tooling
|
||||||
|
:marked
|
||||||
|
Install **[Node.js® and npm](https://nodejs.org/en/download/)**
|
||||||
|
if they are not already on your machine.
|
||||||
|
.l-sub-section
|
||||||
|
:marked
|
||||||
|
**Verify that you are running at least node `v4.x.x` and npm `3.x.x`**
|
||||||
|
by running `node -v` and `npm -v` in a terminal/console window.
|
||||||
|
Older versions produce errors.
|
||||||
|
|
||||||
|
.l-main-section
|
||||||
|
.callout.is-helpful
|
||||||
|
header Download the source
|
||||||
|
:marked
|
||||||
|
Instead of following each step of these instructions, we can
|
||||||
|
[download the QuickStart source](!{_quickstartSrcURL})
|
||||||
|
from GitHub and follow its brief instructions.
|
||||||
|
|
||||||
|
.l-main-section
|
||||||
|
button(class="verbose off md-primary md-button md-ink-ripple", type="button", onclick="verbose(false)").
|
||||||
|
Hide explanations
|
||||||
|
button(class="verbose on md-primary md-button md-ink-ripple", type="button", onclick="verbose(true)").
|
||||||
|
View explanations
|
||||||
|
.l-verbose-section
|
||||||
|
:marked
|
||||||
|
*Explanations* describe the concepts and reasons behind the instructions.
|
||||||
|
Explanations have a thin border on the left like *this* block of text.
|
||||||
|
|
||||||
|
Click *Hide Explanations* to show only the instructions.
|
||||||
|
Click *View Explanations* to see everything again.
|
||||||
|
|
||||||
|
.l-sub-section
|
||||||
|
:marked
|
||||||
|
We'll see many code blocks as we build the QuickStart app. They're all easy to copy and paste:
|
||||||
|
code-example(format="nocode").
|
||||||
|
Click the glyph on the right to copy code snippets to the clipboard ==>
|
||||||
|
|
||||||
|
- var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'package definition and configuration files'
|
||||||
|
|
||||||
|
.l-main-section#create-and-configure
|
||||||
|
:marked
|
||||||
|
## Step 1: Create and configure the project
|
||||||
|
|
||||||
|
In this step we:
|
||||||
|
* [(a) Create the project folder](#create-the-project-folder)
|
||||||
|
* [(b) Add #{_package_and_config_files}](#add-config-files)
|
||||||
|
* [(c) #{_Install} packages](#install-packages)
|
||||||
|
|
||||||
|
### (a) Create the project folder
|
||||||
|
|
||||||
|
- var _ = _docsFor == 'dart' ? '_' : '-';
|
||||||
|
code-example(language="sh").
|
||||||
|
mkdir angular2!{_}quickstart
|
||||||
|
cd angular2!{_}quickstart
|
||||||
|
|
||||||
|
h3#add-config-files (b) Add #{_package_and_config_files}
|
||||||
|
block package-and-config-files
|
||||||
|
- var _tsconfigUri = 'guide/typescript-configuration.html#tsconfig'
|
||||||
|
- var _typingsUri = 'guide/typescript-configuration.html#!#typings'
|
||||||
|
|
||||||
|
p Add the following package definition and configuration files to the project folder:
|
||||||
|
ul
|
||||||
|
li.
|
||||||
|
#[b package.json] lists packages the QuickStart app depends on and
|
||||||
|
defines some useful scripts.
|
||||||
|
See #[a(href="guide/npm-packages.html") Npm Package Configuration] for details.
|
||||||
|
li.
|
||||||
|
#[b tsconfig.json] is the TypeScript compiler configuration file.
|
||||||
|
See #[a(href="#{_tsconfigUri}") TypeScript Configuration] for details.
|
||||||
|
li.
|
||||||
|
#[b typings.json] identifies TypeScript definition files.
|
||||||
|
See #[a(href="#{_typingsUri}") TypeScript Configuration] for details.
|
||||||
|
li.
|
||||||
|
#[b systemjs.config.js], the SystemJS configuration file.
|
||||||
|
See discussion #[a(href="#systemjs") below].
|
||||||
|
|
||||||
|
a#config-files
|
||||||
|
+makeTabs(`
|
||||||
|
quickstart/ts/package.1.json,
|
||||||
|
quickstart/ts/tsconfig.1.json,
|
||||||
|
quickstart/ts/typings.1.json,
|
||||||
|
quickstart/ts/systemjs.config.1.js
|
||||||
|
`, '', `
|
||||||
|
package.json,
|
||||||
|
tsconfig.json,
|
||||||
|
typings.json,
|
||||||
|
systemjs.config.js
|
||||||
|
`)
|
||||||
|
|
||||||
|
h3#install-packages (c) #{_Install} packages
|
||||||
|
block install-packages
|
||||||
|
:marked
|
||||||
|
We install the packages listed in `package.json` using `npm`. Enter the
|
||||||
|
following command in a terminal window (command window in Windows):
|
||||||
|
|
||||||
|
code-example(language="sh").
|
||||||
|
npm install
|
||||||
|
|
||||||
|
.l-sub-section
|
||||||
|
:marked
|
||||||
|
The `typings` folder could not show up after `npm install`. If so, please install them manually.
|
||||||
|
|
||||||
|
code-example(language="sh").
|
||||||
|
npm run typings install
|
||||||
|
|
||||||
|
.alert.is-important
|
||||||
|
:marked
|
||||||
|
Scary <span style="color:red; font-weight: bold">error messages in red</span> may appear **during** install.
|
||||||
|
The install typically recovers from these errors and finishes successfully.
|
||||||
|
.l-verbose-section(class="l-verbose-inherit")
|
||||||
|
:marked
|
||||||
|
#### npm errors and warnings
|
||||||
|
|
||||||
|
All is well if there are no console messages starting with `npm ERR!` *at the end* of **npm install**.
|
||||||
|
There might be a few `npm WARN` messages along the way — and that is perfectly fine.
|
||||||
|
|
||||||
|
We often see an `npm WARN` message after a series of `gyp ERR!` messages.
|
||||||
|
Ignore them. A package may try to recompile itself using `node-gyp`.
|
||||||
|
If the recompile fails, the package recovers (typically with a pre-built version)
|
||||||
|
and everything works.
|
||||||
|
|
||||||
|
Just make sure there are no `npm ERR!` messages at the end of `npm install`.
|
||||||
|
|
||||||
|
.l-verbose-section
|
||||||
|
:marked
|
||||||
|
#### Adding the libraries and packages we need with *npm*
|
||||||
|
Angular application developers rely on the _[npm](https://docs.npmjs.com)_
|
||||||
|
package manager to install the libraries and packages their apps require.
|
||||||
|
The Angular team recommends the starter-set of packages specified in the
|
||||||
|
`dependencies` and `devDependencies` sections.
|
||||||
|
See the [npm packages](guide/npm-packages.html) chapter for details.
|
||||||
|
|
||||||
|
#### Helpful scripts
|
||||||
|
We've included a number of npm scripts in our suggested `package.json` to handle common development tasks:
|
||||||
|
+makeJson('quickstart/ts/package.1.json',{ paths: 'scripts'}, 'package.json (scripts)')(format=".")
|
||||||
|
|
||||||
|
:marked
|
||||||
|
We execute most npm scripts in the following way: `npm run` followed by a *script-name*.
|
||||||
|
Some commands (such as `start`) don't require the `run` keyword.
|
||||||
|
|
||||||
|
Here's what these scripts do:
|
||||||
|
|
||||||
|
* `npm start` - runs the compiler and a server at the same time, both in "watch mode"
|
||||||
|
|
||||||
|
* `npm run tsc` - runs the TypeScript compiler once
|
||||||
|
|
||||||
|
* `npm run tsc:w` - runs the TypeScript compiler in watch mode;
|
||||||
|
the process keeps running, awaiting changes to TypeScript files and recompiling when it sees them
|
||||||
|
|
||||||
|
* `npm run lite` - runs the <a href="https://www.npmjs.com/package/lite-server" target="_blank">lite-server</a>,
|
||||||
|
a light-weight, static file server with excellent support for Angular apps that use routing
|
||||||
|
|
||||||
|
* `npm run typings` - runs the [*typings* tool](#{_typingsUri}) separately
|
||||||
|
|
||||||
|
* `npm run postinstall` - called by *npm* automatically *after* it successfully completes package installation.
|
||||||
|
This script installs the [TypeScript definition files](#{_typingsUri}) defined in `typings.json`
|
||||||
|
|
||||||
|
:marked
|
||||||
|
**We're all set.** Let's write some code.
|
||||||
|
|
||||||
|
.l-main-section#root-component
|
||||||
|
:marked
|
||||||
|
## Step 2: Our first Angular component
|
||||||
|
|
||||||
|
Let's create a folder to hold our application and add a super-simple Angular component.
|
||||||
|
|
||||||
|
**Create #{_an} #{_appDir} subfolder** off the project root directory:
|
||||||
|
|
||||||
|
code-example.
|
||||||
|
mkdir #{_appDir}
|
||||||
|
|
||||||
|
a#app-component
|
||||||
|
p.
|
||||||
|
#[b Create the component file]
|
||||||
|
#[code #[+adjExPath('app/app.component.ts')]] (in this newly created directory) with the following content:
|
||||||
|
|
||||||
|
+makeExample('app/app.component.ts')
|
||||||
|
|
||||||
|
.l-verbose-section
|
||||||
|
:marked
|
||||||
|
### AppComponent is the root of the application
|
||||||
|
|
||||||
|
Every Angular app has at least one **root component**, conventionally named `AppComponent`,
|
||||||
|
that hosts the client user experience.
|
||||||
|
Components are the basic building blocks of Angular applications.
|
||||||
|
A component controls a portion of the screen — a *view* — through its associated template.
|
||||||
|
|
||||||
|
This QuickStart has only one, extremely simple component.
|
||||||
|
But it has the essential structure of every component we'll ever write:
|
||||||
|
|
||||||
|
* One or more [import](#component-import)
|
||||||
|
statements to reference the things we need.
|
||||||
|
* A [@Component #{_decorator}](#component-decorator)
|
||||||
|
that tells Angular what template to use and how to create the component.
|
||||||
|
* A [component class](#component-class)
|
||||||
|
that controls the appearance and behavior of a view through its template.
|
||||||
|
|
||||||
|
a#component-import
|
||||||
|
:marked
|
||||||
|
### Import
|
||||||
|
|
||||||
|
Angular apps are modular. They consist of many files each dedicated to a purpose.
|
||||||
|
Angular itself is modular. It is a collection of library modules
|
||||||
|
each made up of several, related features that we'll use to build our application.
|
||||||
|
|
||||||
|
When we need something from a module or library, we import it.
|
||||||
|
Here we import the Angular 2 core so that our component code can have access to
|
||||||
|
the `@Component` #{_decorator}.
|
||||||
|
|
||||||
|
+makeExcerpt('app/app.component.ts', 'import')
|
||||||
|
|
||||||
|
h3#component-decorator @Component #{_decorator}
|
||||||
|
+ifDocsFor('ts')
|
||||||
|
:marked
|
||||||
|
`Component` is a *decorator function* that takes a *metadata object* as argument.
|
||||||
|
We apply this function to the component class by prefixing the function with the
|
||||||
|
**@** symbol and invoking it with a metadata object, just above the class.
|
||||||
|
:marked
|
||||||
|
`@Component` is #{_a} *#{_decorator}* that allows us to associate *metadata* with the
|
||||||
|
component class.
|
||||||
|
The metadata tells Angular how to create and use this component.
|
||||||
|
|
||||||
|
+makeExcerpt('app/app.component.ts', 'metadata')
|
||||||
|
|
||||||
|
block annotation-fields
|
||||||
|
:marked
|
||||||
|
This particular metadata object has two fields, a `selector` and a `template`.
|
||||||
|
:marked
|
||||||
|
The **selector** specifies a simple CSS selector for an HTML element that represents the component.
|
||||||
|
|
||||||
|
>The element for this component is named `my-app`.
|
||||||
|
Angular creates and displays an instance of our `AppComponent`
|
||||||
|
wherever it encounters a `my-app` element in the host HTML.
|
||||||
|
|
||||||
|
The **template** specifies the component's companion template,
|
||||||
|
written in an enhanced form of HTML that tells Angular how to render this component's view.
|
||||||
|
|
||||||
|
>Our template is a single line of HTML announcing "*My First Angular 2 App*".
|
||||||
|
|
||||||
|
>A more advanced template could contain data bindings to component properties
|
||||||
|
and might identify other application components which have their own templates.
|
||||||
|
These templates might identify yet other components.
|
||||||
|
In this way an Angular application becomes a tree of components.
|
||||||
|
|
||||||
|
:marked
|
||||||
|
### Component class
|
||||||
|
At the bottom of the file is an empty, do-nothing class named `AppComponent`.
|
||||||
|
+makeExcerpt('app/app.component.ts', 'class')
|
||||||
|
:marked
|
||||||
|
When we're ready to build a substantive application,
|
||||||
|
we can expand this class with properties and application logic.
|
||||||
|
Our `AppComponent` class is empty because we don't need it to do anything in this QuickStart.
|
||||||
|
+ifDocsFor('ts')
|
||||||
|
:marked
|
||||||
|
We **export** `AppComponent` so that we can **import** it elsewhere in our application,
|
||||||
|
as we'll see when we create `app.module.ts`.
|
||||||
|
|
||||||
|
+ifDocsFor('ts')
|
||||||
|
.l-main-section#ngmodule
|
||||||
|
:marked
|
||||||
|
## Step 3: Our own `app.module.ts`
|
||||||
|
|
||||||
|
We compose Angular apps into closely related blocks of functionality with [Angular Modules](guide/ngmodule.html).
|
||||||
|
Every app requires at least one module, the _root module_, that we call `AppModule` by convention.
|
||||||
|
|
||||||
|
Create the file `app/app.module.ts` with the following content:
|
||||||
|
|
||||||
|
+makeExample('app/app.module.ts')(format='.')
|
||||||
|
|
||||||
|
.l-verbose-section
|
||||||
|
:marked
|
||||||
|
We're passing metadata to the `NgModule` decorator function:
|
||||||
|
|
||||||
|
1. `imports` - the _other_ modules that export material we need in _this_ module.
|
||||||
|
Almost every application's _root module_ should import the `BrowserModule`.
|
||||||
|
|
||||||
|
1. `declarations` - components and directives that belong to _this_ module.
|
||||||
|
|
||||||
|
1. `bootstrap` - identifies the _root component_ that Angular should _bootstrap_ when it starts the application.
|
||||||
|
|
||||||
|
We import our lone `app.component.ts` and add it to both the `declarations` and `bootstrap` arrays.
|
||||||
|
|
||||||
|
### Angular Modules import other modules
|
||||||
|
Notice that we also add the `BrowserModule` from `@angular/platform-browser` to the `imports` array.
|
||||||
|
This is the Angular Module that contains all the needed Angular bits and pieces to run our app in the browser.
|
||||||
|
|
||||||
|
Angular itself is split into separate Angular Modules so we only need to import the ones we really use.
|
||||||
|
|
||||||
|
One of the most common ones is `FormsModule`, and soon we'll also see `RouterModule` and `HttpModule`.
|
||||||
|
|
||||||
|
.l-main-section
|
||||||
|
h2#main Step !{step++}: Add #[code #[+adjExPath('main.ts')]]
|
||||||
|
|
||||||
|
block create-main
|
||||||
|
:marked
|
||||||
|
Now we need something to tell Angular to load the app module.
|
||||||
|
Create the file `app/main.ts` with the following content:
|
||||||
|
|
||||||
|
+makeExample('app/main.ts')
|
||||||
|
|
||||||
|
- var _pBD_bootstrapModule = _docsFor == 'dart' ? _bootstrapModule : 'platformBrowserDynamic().bootstrapModule'
|
||||||
|
.l-verbose-section
|
||||||
|
:marked
|
||||||
|
We import the two things we need to launch the application:
|
||||||
|
|
||||||
|
1. Angular's browser `!{_platformBrowserDynamicVsBootStrap}` function
|
||||||
|
1. The application !{_moduleVsRootComp}, `!{_AppModuleVsAppComp}`.
|
||||||
|
|
||||||
|
Then we call `!{_pBD_bootstrapModule}` with `AppComponent`.
|
||||||
|
|
||||||
|
### Bootstrapping is platform-specific
|
||||||
|
|
||||||
|
Notice that we import the `!{_platformBrowserDynamicVsBootStrap}` function
|
||||||
|
from `#{_angular_browser_uri}`, not `#{_angular_core_uri}`.
|
||||||
|
Bootstrapping isn't core because there isn't a single way to bootstrap the app.
|
||||||
|
True, most applications that run in a browser call the bootstrap function from
|
||||||
|
this library.
|
||||||
|
|
||||||
|
But it is possible to load a !{_moduleVsComp} in a different environment.
|
||||||
|
We might load it on a mobile device with [Apache Cordova](https://cordova.apache.org/) or [NativeScript](https://www.nativescript.org/).
|
||||||
|
We might wish to render the first page of our application on the server
|
||||||
|
to improve launch performance or facilitate
|
||||||
|
[SEO](http://www.google.com/webmasters/docs/search-engine-optimization-starter-guide.pdf).
|
||||||
|
These targets require a different kind of bootstrap function that we'd import from a different library.
|
||||||
|
|
||||||
|
### Why create separate *<span ngio-ex>main.ts</span>*<span if-docs="ts">, app module</span> and app component files?
|
||||||
|
|
||||||
|
Then <span ngio-ex>main.ts</span><span if-docs="ts">, app module</span>
|
||||||
|
and the app component files are tiny.
|
||||||
|
This is just a QuickStart.
|
||||||
|
We could have merged these files into one and spared ourselves some complexity.
|
||||||
|
|
||||||
|
We'd rather demonstrate the proper way to structure an Angular application.
|
||||||
|
App bootstrapping is a separate concern from<span if-docs="ts"> creating a module or</span>
|
||||||
|
presenting a view.
|
||||||
|
Mixing concerns creates difficulties down the road.
|
||||||
|
We might launch the `!{_AppModuleVsAppComp}` in multiple environments with different bootstrappers.
|
||||||
|
Testing the component is much easier if it doesn't also try to run the entire application.
|
||||||
|
Let's make the small extra effort to do it *the right way*.
|
||||||
|
|
||||||
|
.l-main-section
|
||||||
|
h2#index Step !{step++}: Add #[code index.html]
|
||||||
|
:marked
|
||||||
|
In the *#{_indexHtmlDir}* folder
|
||||||
|
create an `index.html` file and paste the following lines into it:
|
||||||
|
|
||||||
|
+makeExample('index.html')
|
||||||
|
|
||||||
|
.l-verbose-section
|
||||||
|
:marked
|
||||||
|
The `index.html` file defines the web page that hosts the application.
|
||||||
|
|
||||||
|
+ifDocsFor('ts')
|
||||||
|
:marked
|
||||||
|
The noteworthy sections of HTML are:
|
||||||
|
|
||||||
|
1. The JavaScript [libraries](#libraries)
|
||||||
|
2. Configuration file for [SystemJS](#systemjs), and a script
|
||||||
|
where we import and run the `app` module which refers to the `main` file that we just wrote.
|
||||||
|
3. The [`<my-app>`](#my-app) tag in the `<body>` which is *where our app lives!*
|
||||||
|
|
||||||
|
:marked
|
||||||
|
### Libraries
|
||||||
|
We loaded the following scripts
|
||||||
|
+makeExcerpt('index.html', 'libraries')
|
||||||
|
:marked
|
||||||
|
We begin with `core-js`'s ES2015/ES6 shim which monkey patches the global context (window) with essential features of ES2015 (ES6).
|
||||||
|
Next are the polyfills for Angular2, `zone.js` and `reflect-metadata`.
|
||||||
|
Then the [SystemJS](#systemjs) library for module loading.
|
||||||
|
|
||||||
|
We'll make different choices as we gain experience and
|
||||||
|
become more concerned about production qualities such as
|
||||||
|
load times and memory footprint.
|
||||||
|
|
||||||
|
h3#systemjs SystemJS
|
||||||
|
:marked
|
||||||
|
QuickStart uses <a href="https://github.com/systemjs/systemjs" target="_blank">SystemJS</a>
|
||||||
|
to load application and library modules. [Earlier](#add-config-files) we
|
||||||
|
added the `systemjs.config.js` file to the project root.
|
||||||
|
There are alternatives that work just fine including the well-regarded
|
||||||
|
[webpack](guide/webpack.html).
|
||||||
|
SystemJS happens to be a good choice.
|
||||||
|
But we want to be clear that it was a *choice* and not a *preference*.
|
||||||
|
|
||||||
|
All module loaders require configuration and all loader configuration
|
||||||
|
becomes complicated rather quickly as soon as the file structure diversifies and
|
||||||
|
we start thinking about building for production and performance.
|
||||||
|
|
||||||
|
We suggest becoming well-versed in the loader of your choice.
|
||||||
|
Learn more about SystemJS configuration
|
||||||
|
<a href="https://github.com/systemjs/systemjs/blob/master/docs/config-api.md" target="_blank">here</a>.
|
||||||
|
|
||||||
|
With those cautions in mind, what are we doing in the
|
||||||
|
QuickStart [`systemjs.config.js` configuration file we added earlier](#config-files)?
|
||||||
|
First, we create a map to tell SystemJS where to look when we import some module.
|
||||||
|
Then, we register all our packages to SystemJS:
|
||||||
|
all the project dependencies and our application package, `app`.
|
||||||
|
|
||||||
|
.l-sub-section
|
||||||
|
:marked
|
||||||
|
Our QuickStart doesn't use all of the listed packages
|
||||||
|
but any substantial application will want many of them
|
||||||
|
and all of the listed packages are required by at least one of the documentation samples.
|
||||||
|
|
||||||
|
There is no runtime harm in listing packages that we don't need as they will only be loaded when requested.
|
||||||
|
:marked
|
||||||
|
The `app` package tells SystemJS what to do when it sees a request for a
|
||||||
|
module from the `app/` folder.
|
||||||
|
|
||||||
|
Our QuickStart makes such requests when one of its
|
||||||
|
application TypeScript files has an import statement like this:
|
||||||
|
+makeExcerpt('app/main.ts', 'import')
|
||||||
|
:marked
|
||||||
|
Notice that the module name (after `from`) does not mention a filename extension.
|
||||||
|
In the configuration we tell SystemJS to default the extension to `js`, a JavaScript file.
|
||||||
|
|
||||||
|
That makes sense because we transpile TypeScript to JavaScript
|
||||||
|
*before* running the application.
|
||||||
|
|
||||||
|
.l-sub-section
|
||||||
|
:marked
|
||||||
|
#### Transpiling in the browser
|
||||||
|
In the live example on plunker we transpile (AKA compile) to JavaScript in the browser
|
||||||
|
on the fly. _That's fine for a demo_.
|
||||||
|
|
||||||
|
**Do not transpile in the browser during development or for production**.
|
||||||
|
|
||||||
|
We strongly recommend transpiling (AKA compiling) to JavaScript during a build phase
|
||||||
|
before running the application for several reasons including:
|
||||||
|
|
||||||
|
* We see compiler warnings and errors that are hidden from us in the browser.
|
||||||
|
|
||||||
|
* Precompilation simplifies the module loading process and
|
||||||
|
it's much easier to diagnose problems when this is a separate, external step.
|
||||||
|
|
||||||
|
* Precompilation means a faster user experience because the browser doesn't waste time compiling.
|
||||||
|
|
||||||
|
* We iterate development faster because we only recompile changed files.
|
||||||
|
We notice the difference as soon as the app grows beyond a handful of files.
|
||||||
|
|
||||||
|
* Precompilation fits into a continuous integration process of build, test, deploy.
|
||||||
|
|
||||||
|
:marked
|
||||||
|
The `System.import` call tells SystemJS to import the `main` file
|
||||||
|
(`main.js` ... after transpiling `main.ts`, remember?);
|
||||||
|
`main` is where we tell Angular to launch the application.
|
||||||
|
We also catch and log launch errors to the console.
|
||||||
|
|
||||||
|
All other modules are loaded upon request
|
||||||
|
either by an import statement or by Angular itself.
|
||||||
|
|
||||||
|
### *<my-app>*
|
||||||
|
|
||||||
|
a#my-app
|
||||||
|
:marked
|
||||||
|
When Angular calls the `!{_bootstrapModule}` function in <span ngio-ex>main.ts</span>,
|
||||||
|
it reads the `!{_AppModuleVsAppComp}` metadata<span if-docs="ts">, sees that
|
||||||
|
`AppComponent` is the bootstrap component</span>,
|
||||||
|
finds the `my-app` selector, locates an element tag named `my-app`,
|
||||||
|
and renders our application's view between those tags.
|
||||||
|
|
||||||
|
:marked
|
||||||
|
### Add some style
|
||||||
|
Styles aren't essential but they're nice, and `index.html` assumes we have
|
||||||
|
a stylesheet called `styles.css`.
|
||||||
|
|
||||||
|
Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling,
|
||||||
|
perhaps with the minimal styles shown below.
|
||||||
|
|
||||||
|
+makeExcerpt('styles.css (excerpt)', 'quickstart')
|
||||||
|
|
||||||
|
.callout.is-helpful
|
||||||
|
:marked
|
||||||
|
For the full set of master styles used by the documentation samples,
|
||||||
|
see [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css).
|
||||||
|
|
||||||
|
.l-main-section#build-and-run
|
||||||
|
h2 Step !{step++}: Build and run the app!
|
||||||
|
block run-app
|
||||||
|
:marked
|
||||||
|
Open a terminal window and enter this command:
|
||||||
|
code-example.
|
||||||
|
npm start
|
||||||
|
:marked
|
||||||
|
That command runs two parallel node processes
|
||||||
|
1. The TypeScript compiler in watch mode
|
||||||
|
1. A static server called **lite-server** that loads `index.html` in a browser
|
||||||
|
and refreshes the browser when application files change
|
||||||
|
|
||||||
|
In a few moments, a browser tab should open and display
|
||||||
|
|
||||||
|
figure.image-display
|
||||||
|
img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app")
|
||||||
|
|
||||||
|
:marked
|
||||||
|
**Great job!**
|
||||||
|
|
||||||
|
block build-app
|
||||||
|
//- Nothing for ts.
|
||||||
|
|
||||||
|
:marked
|
||||||
|
## Make some changes
|
||||||
|
|
||||||
|
Try changing the message to "My SECOND Angular 2 app".
|
||||||
|
block server-watching
|
||||||
|
:marked
|
||||||
|
The TypeScript compiler and `lite-server` are watching.
|
||||||
|
They should detect the change, recompile the TypeScript into JavaScript,
|
||||||
|
refresh the browser, and display the revised message.
|
||||||
|
It's a nifty way to develop an application!
|
||||||
|
|
||||||
|
We close the terminal window when we're done to terminate both the compiler and the server.
|
||||||
|
|
||||||
|
.l-main-section
|
||||||
|
:marked
|
||||||
|
# Wrap up
|
||||||
|
|
||||||
|
Our final project folder structure looks like this:
|
||||||
|
block project-file-structure
|
||||||
|
.filetree
|
||||||
|
.file angular2-quickstart
|
||||||
|
.children
|
||||||
|
.file app
|
||||||
|
.children
|
||||||
|
.file app.component.ts
|
||||||
|
.file app.module.ts
|
||||||
|
.file main.ts
|
||||||
|
.file node_modules ...
|
||||||
|
.file typings ...
|
||||||
|
.file index.html
|
||||||
|
.file package.json
|
||||||
|
.file styles.css
|
||||||
|
.file systemjs.config.js
|
||||||
|
.file tsconfig.json
|
||||||
|
.file typings.json
|
||||||
|
:marked
|
||||||
|
Here are the file contents:
|
||||||
|
|
||||||
|
block project-files
|
||||||
|
+makeTabs(`
|
||||||
|
quickstart/ts/app/app.component.ts,
|
||||||
|
quickstart/ts/app/app.module.ts,
|
||||||
|
quickstart/ts/app/main.ts,
|
||||||
|
quickstart/ts/index.html,
|
||||||
|
quickstart/ts/package.1.json,
|
||||||
|
quickstart/ts/tsconfig.1.json,
|
||||||
|
quickstart/ts/typings.1.json,
|
||||||
|
quickstart/ts/styles.1.css,
|
||||||
|
quickstart/ts/systemjs.config.1.js`
|
||||||
|
,
|
||||||
|
',,,,,,,,',
|
||||||
|
`app/app.component.ts,
|
||||||
|
app/app.module.ts,
|
||||||
|
app/main.ts,
|
||||||
|
index.html,
|
||||||
|
package.json,
|
||||||
|
tsconfig.json,
|
||||||
|
typings.json,
|
||||||
|
styles.css,
|
||||||
|
systemjs.config.js`)
|
||||||
|
|
||||||
|
.l-main-section
|
||||||
|
:marked
|
||||||
|
## What next?
|
||||||
|
Our first application doesn't do much. It's basically "Hello, World" for Angular 2.
|
||||||
|
|
||||||
|
We kept it simple in our first pass: we wrote a little Angular component,
|
||||||
|
created a simple `index.html`, and launched with a
|
||||||
|
static file server. That's about all we'd expect to do for a "Hello, World" app.
|
||||||
|
|
||||||
|
**We have greater ambitions!**
|
||||||
|
+ifDocsFor('ts')
|
||||||
|
:marked
|
||||||
|
The good news is that the overhead of setup is (mostly) behind us.
|
||||||
|
We'll probably only touch the `package.json` to update libraries.
|
||||||
|
We'll likely open `index.html` only if we need to add a library or some css stylesheets.
|
||||||
|
:marked
|
||||||
|
We're about to take the next step and build a small application that
|
||||||
|
demonstrates the great things we can build with Angular 2.
|
||||||
|
|
||||||
|
Join us on the [Tour of Heroes Tutorial](./tutorial)!
|
||||||
Loading…
Reference in New Issue