iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(quickstart-ts/dart): updated prose and example code; consolidate for TS&Dart 

closes #1396
This commit is contained in:
Patrice Chalin 2016-05-14 17:40:52 -07:00 committed by Ward Bell
parent a3400d035c
commit fedc39dd52
12 changed files with 605 additions and 599 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
public/_includes/_util-fns.jade
View File

@ -4,6 +4,10 @@
//- Should be one of: 'ts', 'dart' or 'js'. Set in lang specific _util-fns file. //- Should be one of: 'ts', 'dart' or 'js'. Set in lang specific _util-fns file.
- var _docsFor = ''; - var _docsFor = '';
//- Should match `_docsFor`, but in this case provides the full capitalized
//- name of the language.
- var _Lang = 'TypeScript';
//- Simple "macros" used via interpolation in text: //- Simple "macros" used via interpolation in text:
//- e.g., the #{_priv}el variable has an `@Input` #{_decorator}. //- e.g., the #{_priv}el variable has an `@Input` #{_decorator}.
@ -11,8 +15,14 @@
//- preceded by the article "a". (E.g., will be "annotation" for Dart) //- preceded by the article "a". (E.g., will be "annotation" for Dart)
- var _decorator = 'decorator'; - var _decorator = 'decorator';
//- Articles (which toggle between 'a' and 'an'). Used for, e.g.,
//- array vs. list; decorator vs. annotation.
- var _a = 'a';
- var _an = 'an';
//- TS arrays vs. Dart lists //- TS arrays vs. Dart lists
- var _array = 'array'; - var _array = 'array';
//- Deprecate now that we have the articles _a and _an
- var _an_array = 'an array'; - var _an_array = 'an array';
//- Promise vs. Future, etc //- Promise vs. Future, etc
@ -48,6 +58,7 @@ mixin makeExample(_filePath, region, _title, stylePatterns)
- var frag = getFrag(filePath, region); - var frag = getFrag(filePath, region);
- var defaultFormat = frag.split('\n').length > 2 ? "linenums" : ""; - var defaultFormat = frag.split('\n').length > 2 ? "linenums" : "";
- var format = attributes.format || defaultFormat; - var format = attributes.format || defaultFormat;
- if (attributes.format === '.') format = '';
- var avoid = !!attributes.avoid; - var avoid = !!attributes.avoid;
if (title) if (title)
@ -58,6 +69,13 @@ mixin makeExample(_filePath, region, _title, stylePatterns)
code-example(language="#{language}" format="#{format}") code-example(language="#{language}" format="#{format}")
!= styleString(frag, stylePatterns) != styleString(frag, stylePatterns)
//- Like makeExample, but doesn't show line numbers and
//- title is appened with `(excerpt)` if it doesn't already
//- end with a parenthetical remark.
mixin makeExcerpt(_filePath, region, _title, stylePatterns)
- if (_title && !_title.match(/\([\w ]+\)$/)) _title = _title + ' (excerpt)';
+makeExample(_filePath, region, _title, stylePatterns)(format='.')
mixin makeTabs(filePaths, regions, tabNames, stylePatterns) mixin makeTabs(filePaths, regions, tabNames, stylePatterns)
- filePaths = strSplit(filePaths); - filePaths = strSplit(filePaths);
- if (adjustExamplePath) filePaths = filePaths.map(adjustExamplePath); - if (adjustExamplePath) filePaths = filePaths.map(adjustExamplePath);

12
public/docs/_examples/quickstart/dart/lib/app_component.dart Normal file
View File

@ -0,0 +1,12 @@
// #docregion
// #docregion import
import 'package:angular2/core.dart';
// #enddocregion import
// #docregion metadata
@Component(
selector: 'my-app',
template: '<h1>My First Angular 2 App</h1>')
// #enddocregion metadata
// #docregion class
class AppComponent {}

6
public/docs/_examples/quickstart/dart/web/main.dart
View File

@ -1,10 +1,8 @@
// #docregion // #docregion
import 'package:angular2/core.dart';
import 'package:angular2/platform/browser.dart'; import 'package:angular2/platform/browser.dart';
@Component(selector: 'my-app', template: '<h1>My First Angular 2 App</h1>') import 'package:angular2_getting_started/app_component.dart';
class AppComponent {}
main() { void main() {
bootstrap(AppComponent); bootstrap(AppComponent);
} }

14
public/docs/_examples/quickstart/dart/web/styles_1.css Normal file
View File

@ -0,0 +1,14 @@
/* #docregion */
h1 {
color: #369;
font-family: Arial, Helvetica, sans-serif;
font-size: 250%;
}
body {
margin: 2em;
}
/*
* See https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css
* for the full set of master styles used by the documentation samples
*/

4
public/docs/_examples/quickstart/ts/app/app.component.ts
View File

@ -9,6 +9,6 @@ import { Component } from '@angular/core';
template: '<h1>My First Angular 2 App</h1>' template: '<h1>My First Angular 2 App</h1>'
}) })
// #enddocregion metadata // #enddocregion metadata
// #docregion export // #docregion class
export class AppComponent { } export class AppComponent { }
// #enddocregion export // #enddocregion class

19
public/docs/_examples/quickstart/ts/styles.1.css
View File

@ -1,25 +1,14 @@
/* #docregion */ /* #docregion */
/* Master Styles */
h1 { h1 {
color: #369; color: #369;
font-family: Arial, Helvetica, sans-serif; font-family: Arial, Helvetica, sans-serif;
font-size: 250%; font-size: 250%;
} }
h2, h3 {
color: #444;
font-family: Arial, Helvetica, sans-serif;
font-weight: lighter;
}
body { body {
margin: 2em; margin: 2em;
} }
body, input[text], button {
color: #888;
font-family: Cambria, Georgia;
}
/*
* See https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css
* for the full set of master styles used by the documentation samples
*/
/*
* See https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css
* for the full set of master styles used by the documentation samples
*/

3
public/docs/_examples/quickstart/ts/systemjs.config.1.js
View File

@ -39,9 +39,6 @@
packages: packages packages: packages
} }
// filterSystemConfig - index.html's chance to modify config before we register it.
if (global.filterSystemConfig) { global.filterSystemConfig(config); }
System.config(config); System.config(config);
})(this); })(this);

4
public/docs/_examples/systemjs.config.js
View File

@ -1,7 +1,6 @@
/** /**
* System configuration for Angular 2 samples * System configuration for Angular 2 samples
* Adjust as necessary for your application needs. * Adjust as necessary for your application needs.
* Override at the last minute with global.filterSystemConfig (as plunkers do)
*/ */
(function(global) { (function(global) {
@ -42,9 +41,6 @@
packages: packages packages: packages
} }
// filterSystemConfig - index.html's chance to modify config before we register it.
if (global.filterSystemConfig) { global.filterSystemConfig(config); }
System.config(config); System.config(config);
})(this); })(this);

17
public/docs/dart/latest/_util-fns.jade
View File

@ -4,18 +4,21 @@ include ../../../_includes/_util-fns
- var _docsFor = 'dart'; - var _docsFor = 'dart';
- var _decorator = 'annotation'; - var _decorator = 'annotation';
- var _array = 'list'; - var _array = 'list';
- var _an_array = 'a list'; - var _an_array = 'a list'; //- Deprecate now that we have the articles
- var _a = 'an';
- var _an = 'a';
- var _priv = '_'; - var _priv = '_';
- var _Lang = 'Dart';
- var _Promise = 'Future'; - var _Promise = 'Future';
- var _Observable = 'Stream'; - var _Observable = 'Stream';
mixin liveExampleLink(linkText, exampleUrlPartName) mixin liveExampleLink(linkText, exampleUrlPartName)
a(href='https://angular-examples.github.io/#{exampleUrlPartName}')= linkText a(href='https://angular-examples.github.io/#{exampleUrlPartName}' target="_blank")= linkText
mixin liveExampleLink2(linkText, exampleUrlPartName) mixin liveExampleLink2(linkText, exampleUrlPartName)
- var liveExampleSourceLinkText = attributes.srcLinkText || 'view source' - var liveExampleSourceLinkText = attributes.srcLinkText || 'view source'
| #[+liveExampleLink(linkText, exampleUrlPartName)] | #[+liveExampleLink(linkText, exampleUrlPartName)]
| (#[a(href='https://github.com/angular-examples/#{exampleUrlPartName}') #{liveExampleSourceLinkText}]) | (#[a(href='https://github.com/angular-examples/#{exampleUrlPartName}' target="_blank") #{liveExampleSourceLinkText}])
- var adjustExamplePath = function(_path) { - var adjustExamplePath = function(_path) {
- if(!_path) return _path; - if(!_path) return _path;
@ -25,9 +28,11 @@ mixin liveExampleLink2(linkText, exampleUrlPartName)
- // if(extn == 'dart') return path; - // if(extn == 'dart') return path;
- var baseName = getBaseFileName(path) || path; // TODO: have getBaseFileName() return path - var baseName = getBaseFileName(path) || path; // TODO: have getBaseFileName() return path
- var baseNameNoExt = baseName.substr(0,baseName.length - (extn.length + 1)); - var baseNameNoExt = baseName.substr(0,baseName.length - (extn.length + 1));
- var inWebFolder = baseNameNoExt.match(/^(main|index)$/); - var inWebFolder = baseNameNoExt.match(/^(main|index(\.\d)?)$/);
- // Adjust the folder path, e.g., ts -> dart - // Adjust the folder path, e.g., ts -> dart
- folder = folder.replace(/(^|\/)ts\//, '$1dart/').replace(/(^|\/)app($|\/)/, inWebFolder ? '$1web$2' : '$1lib$2'); - folder = folder.replace(/(^|\/)ts($|\/)/, '$1dart$2').replace(/(^|\/)app($|\/)/, inWebFolder ? '$1web$2' : '$1lib$2');
- // Special case not handled above: e.g., index.html -> web/index.html
- if(baseNameNoExt.match(/^(index|styles)(\.\d)?$/)) folder = (folder ? folder + '/' : '') + 'web';
- // In file name, replace special characters with underscore - // In file name, replace special characters with underscore
- baseNameNoExt = baseNameNoExt.replace(/[\-\.]/g, '_'); - baseNameNoExt = baseNameNoExt.replace(/[\-\.]/g, '_');
- // Adjust the file extension - // Adjust the file extension
@ -40,7 +45,7 @@ mixin liveExampleLink2(linkText, exampleUrlPartName)
- var title = _title.trim(); - var title = _title.trim();
- // Assume title is a path if it ends with an extension like '.foo', - // Assume title is a path if it ends with an extension like '.foo',
- // optionally followed by some comment in parentheses. - // optionally followed by some comment in parentheses.
- var matches = title.match(/(.*\.\w+)($|\s*\([\w ]+\)?$)/); - var matches = title.match(/(.*\.\w+)($|\s*\([\w ]+\)$)/);
- if(matches && matches.length == 3) { - if(matches && matches.length == 3) {
- // e.g. matches == ['abc.ts (excerpt)', 'abc.ts', ' (excerpt)'] - // e.g. matches == ['abc.ts (excerpt)', 'abc.ts', ' (excerpt)']
- var path = adjustExamplePath(matches[1]); - var path = adjustExamplePath(matches[1]);

335
public/docs/dart/latest/quickstart.jade
View File

@ -1,136 +1,69 @@
include _util-fns extends ../../ts/latest/quickstart.jade
:marked block includes
Let's start from zero and build a super simple Angular 2 application in Dart. include _util-fns
- var _Install = 'Get'
- var _prereq = 'the Dart SDK'
- var _angular_browser_uri = 'package:angular2/platform/browser.dart'
- var _angular_core_uri = 'package:angular2/core.dart'
- var _appDir = 'lib'
- var _indexHtmlDir = 'web'
.callout.is-helpful block setup-tooling
header Don't want Dart?
:marked :marked
Although we're getting started in Dart, you can also write Angular 2 apps Install the **[Dart SDK](https://www.dartlang.org/downloads/)**,
in TypeScript and JavaScript. if not already on your machine, and any tools you like to use with Dart.
Just select either of those languages from the combo-box in the banner. The Dart SDK includes **[pub][pub]**, the Dart package manager, that we
will be using shortly.
If you don't have a favorite Dart editor already, try
[WebStorm][WS], which comes with a Dart plugin.
You can also download [Dart plugins for other IDEs and editors][DT].
p. [WS]: https://confluence.jetbrains.com/display/WI/Getting+started+with+Dart
These instructions assume that you already have the [DT]: https://www.dartlang.org/tools
<a href="https://www.dartlang.org/downloads/">Dart SDK</a> [pub]: https://www.dartlang.org/tools/pub
and any tools you like to use with Dart.
If you don't have a favorite editor already, try
<a href="https://confluence.jetbrains.com/display/WI/Getting+started+with+Dart">WebStorm</a>,
which comes with a Dart plugin.
You can also download
<a href="https://www.dartlang.org/tools/">Dart plugins for
other IDEs and editors</a>.
Once you have the Dart SDK and any other tools you want, return here.
block download-source
// exclude this section from Dart
//- ########################## block package-and-config-files
.l-main-section
h2#section-install-angular Set up a new app directory
:marked :marked
Create a new directory, In the project folder just created, put a file named
and put a file named `pubspec.yaml` in it. **[pubspec.yaml][pubspec]** in it.
As shown below, in `pubspec.yaml`, specify the angular2 and browser
packages as dependencies, as well as the angular2 transformer.
Angular 2 is still changing, so provide an exact version: **2.0.0-beta.17**.
code-example(language="sh"). [pubspec]: https://www.dartlang.org/tools/pub/pubspec.html
&gt; <span class="blk">mkdir angular2_getting_started</span>
&gt; <span class="blk">cd angular2_getting_started</span>
&gt; <span class="blk">vim pubspec.yaml</span> # Use your favorite editor!
p.
In <code>pubspec.yaml</code>,
specify the angular2 and browser packages as dependencies,
as well as the angular2 transformer.
Angular 2 is still changing, so provide an exact version:
<b>2.0.0-beta.17</b>.
+makeExample('quickstart/dart/pubspec.yaml', 'no-rewriter', 'pubspec.yaml') +makeExample('quickstart/dart/pubspec.yaml', 'no-rewriter', 'pubspec.yaml')
p. block install-packages
In the same directory, create a <code>web</code> directory, and then :marked
run <code>pub get</code> to install the angular2 and browser packages From the project folder, run `pub get` to install the angular2 and browser
(along with the packages they depend on). packages (along with the packages they depend on).
code-example(language="sh"). code-example(language="sh").
&gt; <span class="blk">mkdir web</span>
&gt; <span class="blk">pub get</span> &gt; <span class="blk">pub get</span>
Resolving dependencies... Resolving dependencies...
//- PENDING: Create template? Link to pub/pubspec docs? block annotation-fields
//- ##########################
.l-main-section
h2#section-transpile Create a Dart file
p.
Create a file under <code>web</code> named <code>main.dart</code>.
code-example(language="sh").
&gt; <span class="blk">vim web/main.dart</span> # Use your favorite editor!
p.
Paste the following code into <code>web/main.dart</code>:
+makeExample('quickstart/dart/web/main.dart', null, 'web/main.dart')
:marked :marked
You've just defined an Angular 2 **component**,
one of the most important Angular 2 features.
Components are the primary way to create application views
and support them with application logic.
This component is an empty, do-nothing class named `AppComponent`.
You can add properties and application logic to it later,
when you're ready to build a substantive application.
Above the class is the `@Component` annotation,
which tells Angular that this class *is an Angular component*.
The call to the `@Component` constructor has two The call to the `@Component` constructor has two
named parameters, `selector` and `template`. named parameters, `selector` and `template`.
The `selector` parameter specifies a CSS selector for block create-main
a host HTML element named `my-app`.
Angular creates and displays an instance of `AppComponent`
wherever it encounters a `my-app` element.
The `template` parameter is the component's companion template
that tells Angular how to render a view.
In this case, the template is a single line of HTML announcing
"My First Angular 2 App".
The <code>main()</code> function
calls Angular's <code>bootstrap()</code> function,
which tells Angular to start the application with `AppComponent`
at the application root.
Someday the application will
consist of more components arising in tree-like fashion from this root.
The top lines import two libraries.
*All* Dart files that use Angular APIs import `core.dart`.
Only files that call `bootstrap()` import `platform/browser.dart`.
//- ##########################
.l-main-section
h2#section-angular-create-account Create an HTML file
p. p.
Create a file named <code>web/index.html</code> that contains Now we need something to tell Angular to load the root component.
the following code: Create:
ul
li a #[b folder named #[code web]], and inside it
li the file #[code #[+adjExPath('app/main.ts')]] with the following content:
+makeExample('quickstart/dart/web/index.html', null, 'web/index.html') block index-html-commentary-for-ts
//- N/A
:marked
The `<my-app>` tag in the `<body>` is
the custom HTML element defined in the Dart file.
//- ##########################
.l-main-section
h2#section-angular-run-app Run the app
block run-app
p. p.
You have a few options for running your app. You have a few options for running your app.
One is to launch a local HTTP server One is to launch a local HTTP server
@ -138,102 +71,120 @@ p.
<a href="https://www.dartlang.org/tools/dartium/">Dartium</a>. <a href="https://www.dartlang.org/tools/dartium/">Dartium</a>.
You can use whatever server you like, such as WebStorm's server You can use whatever server you like, such as WebStorm's server
or Python's SimpleHTTPServer. or Python's SimpleHTTPServer.
p. p.
Another option is to build and serve the app using <code>pub serve</code>, Another option is to build and serve the app using <code>pub serve</code>,
and then run it by visiting <b>http://localhost:8080</b> in any modern browser. and then run it by visiting <b><code>http://localhost:8080</code></b> in any modern browser.
Pub serve generates the JavaScript on the fly, Pub serve generates JavaScript on the fly,
which can take a while when you first visit the page. which can take a while when you first visit the page.
Pub serve also runs in <b><i>watch mode</i></b>, and will re-compile and subsequently serve
and changed assets.
p. p.
Once the app is running, Once the app is running, you should see the following in your browser
you should see <b>My First Angular 2 App</b> in your browser window. window:
:marked block build-app
If you don't see that, make sure you've entered all the code correctly .alert.is-important
and run `pub get`. :marked
If you don't see that, make sure you've entered all the code correctly,
in the [proper folders](#wrap-up),
and run `pub get`.
//- ########################## .l-verbose-section
.l-main-section h3#section-angular-run-app Building the app (generating JavaScript)
h2#section-angular-run-app Generate JavaScript :marked
Before you can deploy your app, you need to generate JavaScript files.
The `pub build` command makes that easy.
To improve your app's performance, convert the
HTML file to directly include the generated JavaScript;
one way to do that is with `dart_to_js_script_rewriter`.
:marked Add the `dart_to_js_script_rewriter` package to your pubspec,
Before you can deploy your app, you need to generate JavaScript files. in both the `dependencies` and `transformers` sections.
Pub build makes that easy.
To improve your app's performance, convert the
HTML file to directly include the generated JavaScript;
one way to do that is with dart_to_js_script_rewriter.
:marked - var stylePattern = { pnk: /(dart_to_js_script_rewriter.*$)|(- dart_to_js_script_rewriter.*$)/gm, otl: /(dependencies:)|(transformers:)/g };
Add the dart_to_js_script_rewriter package to your pubspec, +makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
in both the `dependencies` and `transformers` sections.
- var stylePattern = { pnk: /(dart_to_js_script_rewriter.*$)|(- dart_to_js_script_rewriter.*$)/gm, otl: /(dependencies:)|(transformers:)/g };
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
p.
Then compile your Dart code to JavaScript,
using <code>pub build</code>.
code-example(language="basic").
&gt; <span class="blk">pub build</span>
Loading source assets...
p.
The generated JavaScript appears, along with supporting files,
under the <code>build</code> directory.
p.
When you generate JavaScript for an Angular app,
be sure to use the Angular transformer.
It analyzes your code,
converting reflection-using code to static code
that Dart's build tools can compile to faster, smaller JavaScript.
The highlighted lines in <code>pubspec.yaml</code>
configure the Angular transformer:
- var stylePattern = { otl: /(transformers:)|(- angular2:)|(entry_points.*$)/gm };
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
p.
The <code>entry_points</code> item
identifies the Dart file in your app
that has a <code>main()</code> function.
For more information, see the
<a href="https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer">Angular
transformer wiki page</a>.
#performance.l-sub-section
h3 Performance, the transformer, and Angular 2 libraries
p. p.
When you import <code>bootstrap.dart</code>, Then compile your Dart code to JavaScript,
you also get <code>dart:mirrors</code>, using <code>pub build</code>.
a reflection library that
causes performance problems when compiled to JavaScript.
Don't worry,
the Angular transformer converts your entry points
(<code>entry_points</code> in <code>pubspec.yaml</code>)
so that they don't use mirrors.
code-example(language="sh").
&gt; <span class="blk">pub build</span>
Loading source assets...
//- WHAT'S NEXT... ########################## p.
.l-main-section The generated JavaScript appears, along with supporting files,
h2#section-transpile Great job! Next step... under the <code>build</code> directory.
p.
When you generate JavaScript for an Angular app,
be sure to use the Angular transformer.
It analyzes your code,
converting reflection-using code to static code
that Dart's build tools can compile to faster, smaller JavaScript.
The highlighted lines in <code>pubspec.yaml</code>
configure the Angular transformer:
<!--TODO: Join us on the [Tour of Heroes](./toh-pt1.html) --> - var stylePattern = { otl: /(transformers:)|(- angular2:)|(entry_points.*$)/gm };
+makeExample('quickstart/dart/pubspec.yaml', null, 'pubspec.yaml', stylePattern)
p. p.
Follow the <a href="guide">developer guide</a> The <code>entry_points</code> item
to continue playing with Angular 2 for Dart. identifies the Dart file in your app
that has a <code>main()</code> function.
For more information, see the
<a href="https://github.com/angular/angular/wiki/Angular-2-Dart-Transformer">Angular
transformer wiki page</a>.
p. #performance.l-sub-section
Or read more about Angular or Dart: h3 Performance, the transformer, and Angular 2 libraries
p.
When you import <code>bootstrap.dart</code>,
you also get <code>dart:mirrors</code>,
a reflection library that
causes performance problems when compiled to JavaScript.
Don't worry,
the Angular transformer converts your entry points
(<code>entry_points</code> in <code>pubspec.yaml</code>)
so that they don't use mirrors.
ul block server-watching
li :marked
<a href="resources.html">Angular resources</a> Pub serve is watching and
li should detect the change, recompile the Dart into JavaScript,
<a href="https://www.dartlang.org">dartlang.org</a> refresh the browser, and display the revised message.
It's a nifty way to develop an application!
Ensure that you terminate the `pub serve` process once you are done.
block project-file-structure
.filetree
.file angular2-quickstart
.children
.file build ...
.file lib
.children
.file app_component.dart
.file pubspec.yaml
.file web
.children
.file index.html
.file main.ts
.file styles.css
block project-files
+makeTabs(`
quickstart/ts/app/app.component.ts,
quickstart/ts/app/main.ts,
quickstart/ts/index.html,
quickstart/dart/pubspec.yaml,
quickstart/ts/styles.1.css`
,null,
`app/app.component.ts,
app/main.ts,
index.html,
pubspec.yaml,
styles.css`)
block what-next-ts-overhead
//- N/A

2
public/docs/ts/latest/_util-fns.jade
View File

@ -5,7 +5,7 @@ include ../../../_includes/_util-fns
//- Other values match the defaults. //- Other values match the defaults.
mixin liveExampleLink(linkText, exampleUrlPartName) mixin liveExampleLink(linkText, exampleUrlPartName)
a(href='/resources/live-examples/#{exampleUrlPartName}/ts/plnkr.html')= linkText a(href='/resources/live-examples/#{exampleUrlPartName}/ts/plnkr.html' target="_blank")= linkText
mixin liveExampleLink2(linkText, exampleUrlPartName) mixin liveExampleLink2(linkText, exampleUrlPartName)
//- In Dart this also gives a link to the source. //- In Dart this also gives a link to the source.

712
public/docs/ts/latest/quickstart.jade
View File

@ -1,39 +1,65 @@
include _util-fns 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 _appDir = 'app'
- var _indexHtmlDir = 'project root'
:marked :marked
Our QuickStart goal is to build and run a super-simple Angular 2 application in TypeScript. 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.
# Download the code .callout.is-helpful
In a hurry? header Don't want #{_Lang}?
[Download the QuickStart source](https://github.com/angular/quickstart/blob/master/README.md) p.
and start coding. 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.
# See it run h1 Try it!
p
Try this <a href="/resources/live-examples/quickstart/ts/plnkr.html" target="_blank">live example</a> | Try the #[+liveExampleLink2('live example', 'quickstart')] which loads the sample app
which loads the sample app in <a href="http://plnkr.co/" title="Plunker" target="_blank">plunker</a> +ifDocsFor('ts')
and displays a simple message: | &nbsp;in #[a(href="http://plnkr.co/" title="Plunker" target="_blank") plunker]
| &nbsp;and displays the simple message:
figure.image-display figure.image-display
img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app") img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app")
h1 Build this app!
:marked :marked
# Learn - [Prerequisite](#prereq): install #{_prereq}
Of course we don't build apps to run in plunker. - [Step 1](#create-and-configure): create the app’s project folder and
The following steps establish a development environment for the documentation samples define package dependencies and special project setup
that also can be the foundation for our real world applications. At a high level, we will - [Step 2](#root-component): create the app’s Angular root component
- [Step 3](#main): add `main.#{_docsFor}`, identifying the root component to Angular
- [Step 4](#index): add `index.html`, the web page that hosts the application
- [Step 5](#build-and-run): build and run the app
- [Make some changes to the app](#make-some-changes)
- [Wrap up](#wrap-up)
- set up the [development environment](#devenv) .l-main-section
- write the app's Angular [root component](#component) h2#prereq Prerequisite: #{_prereq}
- write [main.ts](#main) which tells Angular to display the root component
- write the [host web page](#index) (`index.html`)
.l-sub-section block setup-tooling
:marked :marked
We'll see many code blocks as we pursue this agenda. They're all easy to copy and paste: Install **[Node.js® and npm](https://nodejs.org/en/download/)**
code-example(format='.', language='html'). if they are not already on your machine.
Click the glyph on the right to copy code snippets to the clipboard ⇨⇨⇨⇨⇨⇨⇨⇨⇨⇨
block download-source
.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](https://github.com/angular/quickstart/blob/master/README.md)
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)"). button(class="verbose off md-primary md-button md-ink-ripple", type="button", onclick="verbose(false)").
Hide explanations Hide explanations
button(class="verbose on md-primary md-button md-ink-ripple", type="button", onclick="verbose(true)"). button(class="verbose on md-primary md-button md-ink-ripple", type="button", onclick="verbose(true)").
@ -46,188 +72,194 @@ button(class="verbose on md-primary md-button md-ink-ripple", type="button", onc
Click *Hide Explanations* to show only the instructions. Click *Hide Explanations* to show only the instructions.
Click it again to see everything again. Click it again to see everything again.
a(id="devenv") .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 ==>
.l-main-section .l-main-section
:marked h2#create-and-configure Step 1: create and configure the project
## Development Environment
We need to set up our development environment: - var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'package definition and configuration files'
* install node and npm
* create an [application project folder](#app-folder)
* add a [tsconfig.json](#tsconfig) to guide the TypeScript compiler
* add a [typings.json](#typings) that identifies missing TypeScript definition files
* add a [package.json](#package-json) that defines the packages and scripts we need
* add a [systemjs.config.js](#systemjs) that configures system.js
* install the npm packages and typings files
a(id="install-npm")
:marked :marked
**Install [node and npm](https://nodejs.org/en/download/)** if not already on your machine. 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(id="app-folder") h3 (a) Create the project folder
:marked
Create a **new project folder** code-example(language="sh").
code-example(format="").
mkdir angular2-quickstart mkdir angular2-quickstart
cd angular2-quickstart cd angular2-quickstart
a(id="tsconfig") h3#add-config-files (b) Add #{_package_and_config_files}
:marked block package-and-config-files
Add a **tsconfig.json** file to the project folder and copy/paste the following: - var _tsconfigUri = 'guide/typescript-configuration.html#tsconfig'
+makeJson('quickstart/ts/tsconfig.1.json', null, 'tsconfig.json')(format=".") - var _typingsUri = 'guide/typescript-configuration.html#!#typings'
:marked p Add the following package definition and configuration files to the project folder:
This `tsconfig.json` file guides the TypeScript compiler. ul
Learn more about it in the li.
<a href="guide/typescript-configuration.html#tsconfig" target="_blank">TypeScript Configuration</a> chapter. #[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(id="typings") a#config-files
:marked +makeTabs(`
Add a **typings.json** file to the project folder and copy/paste the following: quickstart/ts/package.1.json,
+makeJson('quickstart/ts/typings.1.json', null, 'typings.json')(format=".") 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
`)
.l-verbose-section h3#install-packages (c) #{_Install} packages
block install-packages
:marked :marked
Many JavaScript libraries extend the JavaScript environment with features and syntax We install the packages listed in `package.json` using `npm`. Enter the
that the TypeScript compiler doesn't recognize natively. We teach it about these capabilities with following command in a terminal window (command window in Windows):
<a href="http://www.typescriptlang.org/docs/handbook/writing-declaration-files.html" target="_blank">TypeScript type definition files</a>
&mdash; *d.ts files* &mdash; which we identify in a `typings.json` file.
We go a little deeper into *typings* in the code-example(language="sh").
<a href="guide/typescript-configuration.html#typings" target="_blank">TypeScript Configuration</a> chapter. npm install
a(id="package-json") .alert.is-important
:marked
Add a **package.json** file to the project folder and copy/paste the following:
+makeJson('quickstart/ts/package.1.json', null, 'package.json')(format=".")
.l-verbose-section
:marked
### Adding the libraries we need with *npm*
Angular application developers rely on the <a href="https://docs.npmjs.com/" target="_blank"><i>npm</i></a>
package manager to install the libraries 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` + *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 re-compiling 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](#typings) separately
* `npm run postinstall` - called by *npm* automatically *after* it successfully completes package installation.
This script installs the [TypeScript definition files](#typings) defined in `typings.json`
:marked
**Install these packages** by entering the following *npm* command in a terminal window (command window in Windows):
code-example(format="").
npm 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 :marked
#### npm errors and warnings 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**. 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 &mdash; and that is perfectly fine. There might be a few `npm WARN` messages along the way &mdash; and that is perfectly fine.
We often see an `npm WARN` message after a series of `gyp ERR!` messages. We often see an `npm WARN` message after a series of `gyp ERR!` messages.
Ignore them. A package may try to re-compile itself using `node-gyp`. Ignore them. A package may try to re-compile itself using `node-gyp`.
If the re-compile fails, the package recovers (typically with a pre-built version) If the re-compile fails, the package recovers (typically with a pre-built version)
and everything works. and everything works.
Just make sure there are no `npm ERR!` messages at the end of `npm install`. 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 re-compiling 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 :marked
**We're all set.** Let's write some code. **We're all set.** Let's write some code.
a(id="component")
.l-main-section .l-main-section
h2#root-component Step 2: our first angular component
:marked :marked
## Our First Angular Component
Let's create a folder to hold our application and add a super-simple Angular component. Let's create a folder to hold our application and add a super-simple Angular component.
**Create an *app* sub-folder** off the root directory and make it the current directory **Create an *#{_appDir}* sub-folder** off the project root directory:
code-example(format="").
mkdir app
cd app
a(id="app-component") code-example.
:marked mkdir #{_appDir}
**Add a component file** named *app.component.ts* and paste the following lines:
+makeExample('quickstart/ts/app/app.component.ts', null, 'app/app.component.ts')(format=".") 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('quickstart/ts/app/app.component.ts', '', 'app/app.component.ts')(format='.')
.l-verbose-section .l-verbose-section
:marked :marked
### AppComponent is the root of the application ### AppComponent is the root of the application
Every Angular app has at least one root component, conventionally named `AppComponent`, Every Angular app has at least one **root component**, conventionally named `AppComponent`,
that hosts the client user experience. that hosts the client user experience.
Components are the basic building blocks of Angular applications. Components are the basic building blocks of Angular applications.
A component controls a portion of the screen &mdash; a *view* &mdash; through its associated template. A component controls a portion of the screen &mdash; a *view* &mdash; through its associated template.
This QuickStart has only one, extremely simple component. This QuickStart has only one, extremely simple component.
But it has the essential structure of every component we'll ever write: But it has the essential structure of every component we'll ever write:
* One or more <a href="javascript: why('component-import')">import</a> * One or more [import](#component-import)
statements to reference the things we need. statements to reference the things we need.
* A [@Component #{_decorator}](#component-decorator)
* A <a href="javascript: why('decorator')">@Component decorator</a>
that tells Angular what template to use and how to create the component. that tells Angular what template to use and how to create the component.
* A [component class](#component-class)
* A <a href="javascript: why('class')">component class</a>
that controls the appearance and behavior of a view through its template. that controls the appearance and behavior of a view through its template.
a(id="component-import") a#component-import
:marked :marked
### Import ### Import
Angular apps are modular. They consist of many files each dedicated to a purpose. 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 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. each made up of several, related features that we'll use to build our application.
When we need something from a module, we import it. When we need something from a module or library, we import it.
Here we import the Angular `Component` decorator function from Here we import the Angular 2 core so that our component code can have access to
`@angular/core` because we need it to define our component. the `@Component` #{_decorator}.
+makeExample('quickstart/ts/app/app.component.ts', 'import', 'app/app.component.ts (import)')(format=".")
a(id="component-decorator") +makeExcerpt('quickstart/ts/app/app.component.ts', 'import', '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 :marked
### @Component decorator `@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.
`Component` is a **decorator** function that takes a *metadata* object. +makeExcerpt('quickstart/ts/app/app.component.ts', 'metadata', 'app/app.component.ts (metadata)')(format='.')
The metadata tell Angular how to create and use this component.
We apply this function to the component class block annotation-fields
by prefixing the function with the **@** symbol and invoking it with the metadata object :marked
just above the class: This particular metadata object has two fields, a `selector` and a `template`.
+makeExample('quickstart/ts/app/app.component.ts', 'metadata', 'app/app.component.ts (metadata)')(format=".")
:marked :marked
This particular metadata object has two fields, a `selector` and a `template`.
The **selector** specifies a simple CSS selector for an HTML element that represents the component. The **selector** specifies a simple CSS selector for an HTML element that represents the component.
>The element for this component is named `my-app`. >The element for this component is named `my-app`.
@ -244,27 +276,28 @@ a(id="app-component")
These templates might identify yet other components. These templates might identify yet other components.
In this way an Angular application becomes a tree of components. In this way an Angular application becomes a tree of components.
a(id="component-class")
:marked :marked
### Component class ### Component class
At the bottom of the file is an empty, do-nothing class named `AppComponent`. At the bottom of the file is an empty, do-nothing class named `AppComponent`.
+makeExample('quickstart/ts/app/app.component.ts', 'export', 'app/app.component.ts (class)')(format=".") +makeExcerpt('quickstart/ts/app/app.component.ts', 'class', 'app/app.component.ts (class)')
:marked :marked
When we're ready to build a substantive application, When we're ready to build a substantive application,
we can expand this class with properties and application logic. 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. 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 `main.ts`.
We **export** `AppComponent` so that we can **import** it elsewhere in our application,
as we'll see when we create `main.ts`.
a(id="main")
.l-main-section .l-main-section
:marked h2#main Step 3: add #[code #[+adjExPath('main.ts')]]
## Show it with *main.ts*
Now we need something to tell Angular to load the root component
Add a new file , `main.ts`, to the `app/` folder as follows: block create-main
+makeExample('quickstart/ts/app/main.ts', null, 'app/main.ts')(format=".") p.
Now we need something to tell Angular to load the root component.
Create the file #[code #[+adjExPath('app/main.ts')]] with the following content:
+makeExample('quickstart/ts/app/main.ts', '', 'app/main.ts')(format='.')
.l-verbose-section .l-verbose-section
:marked :marked
@ -276,9 +309,8 @@ a(id="main")
Then we call `bootstrap` with `AppComponent`. Then we call `bootstrap` with `AppComponent`.
### Bootstrapping is platform-specific ### Bootstrapping is platform-specific
Notice that we import the `bootstrap` function from `@angular/platform-browser-dynamic`, Notice that we import the `bootstrap` function from `#{_angular_browser_uri}`,
not `@angular/core`. not `#{_angular_core_uri}`.
Bootstrapping isn't core because there isn't a single way to bootstrap the app. 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 True, most applications that run in a browser call the bootstrap function from
this library. this library.
@ -288,13 +320,13 @@ a(id="main")
We might wish to render the first page of our application on the server We might wish to render the first page of our application on the server
to improve launch performance or facilitate to improve launch performance or facilitate
[SEO](http://www.google.com/webmasters/docs/search-engine-optimization-starter-guide.pdf). [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. These targets require a different kind of bootstrap function that we'd import from a different library.
### Why create a separate ***main.ts*** file? ### Why create separate *main.#{_docsFor}* and app component files?
The *main.ts* file is tiny. This is just a QuickStart. Both `main.#{_docsFor}` and the app component files are tiny.
We could have folded its few lines into the `app.component` file This is just a QuickStart.
We could have merged these two files into one
and spared ourselves some complexity. and spared ourselves some complexity.
We'd rather demonstrate the proper way to structure an Angular application. We'd rather demonstrate the proper way to structure an Angular application.
@ -304,236 +336,230 @@ a(id="main")
Testing the component is much easier if it doesn't also try to run the entire application. 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*. Let's make the small extra effort to do it *the right way*.
a(id="index")
.l-main-section .l-main-section
h2#index Step 4: add #[code index.html]
:marked :marked
## Add the `index.html` The `index.html` is the web page that hosts the application.
The `index.html` is the web page that hosts the application In the **#{_indexHtmlDir}** folder
create an`index.html` file and paste the following lines:
Navigate to the **project root folder**. +makeExample('quickstart/ts/index.html', '', 'index.html')(format='.')
code-example(format="").
cd ..
:marked
Create an`index.html` file in this root folder and paste the following lines:
+makeExample('quickstart/ts/index.html', null, 'index.html')(format=".")
.l-verbose-section
:marked
There are four noteworthy sections of HTML
1. The JavaScript [libraries](#libraries)
2. Configuration file for [SystemJS](#systemjs).
3. Where we import and run the `main` file that we just wrote.
4. The [&lt;my-app>](#my-app) tag in the `<body>` which is *where our app lives!*
a(id="libraries")
:marked
### Libraries
We loaded the following scripts
+makeExample('quickstart/ts/index.html', 'libraries', 'index.html')(format=".")
:marked
We began with 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.
:marked
We'll make different choices as we gain experience and
become more concerned about production qualities such as
load times and memory footprint.
a(id="systemjs")
.l-main-section
:marked
### SystemJS Configuration
The QuickStart uses <a href="https://github.com/systemjs/systemjs" target="_blank">SystemJS</a>
to load application and library modules.
Add this `systemjs.config.js` file to the project root.
+makeExample('quickstart/ts/systemjs.config.1.js', null, 'systemjs.config.js')(format=".")
.l-verbose-section .l-verbose-section
:marked block index-html-commentary-for-ts
There are alternatives that work just fine including the well-regarded
<a href="https://webpack.github.io/" target="_blank">webpack</a>.
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 this QuickStart configuration?
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 :marked
Our QuickStart doesn't use all of the listed packages The noteworthy sections of HTML are:
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. 1. The JavaScript [libraries](#libraries)
:marked 2. Configuration file for [SystemJS](#systemjs), and a script
The `app` package tells SystemJS what to do when it sees a request for a where we import and run the `app` module which refers to the `main` file that we just wrote.
module from the `app/` folder. 3. The [`<my-app>`](#my-app) tag in the `<body>` which is *where our app lives!*
Our QuickStart makes such requests when one of its
application TypeScript files has an import statement like this:
+makeExample('quickstart/ts/app/main.ts', 'app-component', 'main.ts (excerpt)')(format=".")
: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
<i>before</i> running the application</a>.
.l-sub-section
:marked :marked
#### Transpiling in the browser ### Libraries
In the live example on plunker we transpile (AKA compile) to JavaScript in the browser We loaded the following scripts
on the fly. That's fine for a demo. That's not our preference for development or production. +makeExcerpt('quickstart/ts/index.html', 'libraries', 'index.html')
:marked
We begin with 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 recommend transpiling (AKA compiling) to JavaScript during a build phase We'll make different choices as we gain experience and
before running the application for several reasons including: become more concerned about production qualities such as
load times and memory footprint.
* We see compiler warnings and errors that are hidden from us in the browser. 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*.
* Pre-compilation simpifies the module loading process and All module loaders require configuration and all loader configuration
it's much easier to diagnose problems when this is a separate, external step. becomes complicated rather quickly as soon as the file structure diversifies and
we start thinking about building for production and performance.
* Pre-compilation means a faster user experience because the browser doesn't waste time compiling. 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>.
* We iterate development faster because we only re-compile changed files. With those cautions in mind, what are we doing in the
We notice the difference as soon as the app grows beyond a handful of files. 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`.
* Pre-compilation fits into a continuous integration process of build, test, deploy. .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.
:marked There is no runtime harm in listing packages that we don't need as they will only be loaded when requested.
The `System.import` call tells SystemJS to import the `main` file :marked
(`main.js` ... after transpiling `main.ts`, remember?). The `app` package tells SystemJS what to do when it sees a request for a
`main` is where we tell Angular to launch the application. module from the `app/` folder.
We also catch and log launch errors to the console.
All other modules are loaded upon request Our QuickStart makes such requests when one of its
either by an import statement or by Angular itself. application TypeScript files has an import statement like this:
+makeExcerpt('quickstart/ts/app/main.ts', 'app-component', 'main.ts (excerpt)')
: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.
* Pre-compilation simpifies the module loading process and
it's much easier to diagnose problems when this is a separate, external step.
* Pre-compilation means a faster user experience because the browser doesn't waste time compiling.
* We iterate development faster because we only re-compile changed files.
We notice the difference as soon as the app grows beyond a handful of files.
* Pre-compilation 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.
a(id="my-app") a(id="my-app")
:marked :marked
### *&lt;my-app&gt;* ### *&lt;my-app&gt;*
When Angular calls the `bootstrap` function in `main.ts`, it reads the `AppComponent` When Angular calls the `bootstrap` function in `main.#{_docsFor}`, it reads the `AppComponent`
metadata, finds the `my-app` selector, locates an element tag named `my-app`, metadata, finds the `my-app` selector, locates an element tag named `my-app`,
and loads our application between those tags. and renders our application's view between those tags.
.l-main-section
:marked :marked
## Add some style ### Add some style
Styles aren't essential but they're nice and the `index.html` assumes we have Styles aren't essential but they're nice and the `index.html` assumes we have
a stylesheet called `styles.css`. a stylesheet called `styles.css`.
Create a `styles.css` in the root folder and start styling, perhaps with this set: Create a `styles.css` in the #{_indexHtmlDir} folder and start styling, perhaps with minimal
+makeExample('quickstart/ts/styles.1.css', null, 'styles.css (excerpt)')(format=".") styles shown below. For the full set of master styles used by the documentation samples
see this master [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css).
+makeExcerpt('quickstart/ts/styles.1.css', '', 'styles.css')
.l-main-section .l-main-section
:marked h2#build-and-run Step 5: build and run the app!
## Compile and run! 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
Open a terminal window and enter this command: In a few moments, a browser tab should open and display
code-example(format="").
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 figure.image-display
img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of quickstart app") img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of quickstart app")
:marked :marked
Congratulations! We are in business. **Great job!**
### Make some changes block build-app
//- Nothing for ts.
:marked
## Make some changes
Try changing the message to "My SECOND Angular 2 app". 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!
The TypeScript compiler and `lite-server` are watching. We close the terminal window when we're done to terminate both the compiler and the server.
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 .l-main-section
:marked :marked
## Final structure # Wrap up
## Final project structure and files
Our final project folder structure looks like this: Our final project folder structure looks like this:
.filetree block project-file-structure
.file angular2-quickstart .filetree
.children .file angular2-quickstart
.file app
.children .children
.file app.component.ts .file app
.file main.ts .children
.file node_modules ... .file app.component.ts
.file typings ... .file main.ts
.file index.html .file node_modules ...
.file package.json .file typings ...
.file styles.css .file index.html
.file systemjs.config.js .file package.json
.file tsconfig.json .file styles.css
.file typings.json .file systemjs.config.js
.file tsconfig.json
.file typings.json
:marked :marked
And here are the files: And here are the files:
+makeTabs(` block project-files
quickstart/ts/app/app.component.ts, +makeTabs(`
quickstart/ts/app/main.ts, quickstart/ts/app/app.component.ts,
quickstart/ts/index.html, quickstart/ts/app/main.ts,
quickstart/ts/package.1.json, quickstart/ts/index.html,
quickstart/ts/tsconfig.1.json, quickstart/ts/package.1.json,
quickstart/ts/typings.1.json, quickstart/ts/tsconfig.1.json,
quickstart/ts/styles.1.css, quickstart/ts/typings.1.json,
quickstart/ts/systemjs.config.1.js` quickstart/ts/styles.1.css,
,null, quickstart/ts/systemjs.config.1.js`
`app/app.component.ts, ,null,
app/main.ts, `app/app.component.ts,
index.html, app/main.ts,
package.json, index.html,
tsconfig.json, package.json,
typings.json, tsconfig.json,
styles.css, typings.json,
systemjs.config.js`) styles.css,
:marked systemjs.config.js`)
.l-main-section .l-main-section
:marked :marked
## Wrap Up ## What next?
Our first application doesn't do much. It's basically "Hello, World" for Angular 2. 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, We kept it simple in our first pass: we wrote a little Angular component,
we added some JavaScript libraries to `index.html`, and launched with a 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. static file server. That's about all we'd expect to do for a "Hello, World" app.
**We have greater ambitions.** **We have greater ambitions!**
block what-next-ts-overhead
The good news is that the overhead of setup is (mostly) behind us. :marked
We'll probably only touch the `package.json` to update libraries. The good news is that the overhead of setup is (mostly) behind us.
We'll likely open `index.html` only if we need to add a library or some css stylesheets. 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 We're about to take the next step and build a small application that
demonstrates the great things we can build with Angular 2. demonstrates the great things we can build with Angular 2.