461 lines
16 KiB
Plaintext
461 lines
16 KiB
Plaintext
include ../../../_includes/_util-fns
|
|
|
|
:markdown
|
|
Let's start from zero and build a super simple Angular 2 application in TypeScript.
|
|
|
|
.callout.is-helpful
|
|
header Don't want TypeScript?
|
|
:markdown
|
|
Although we're getting started in TypeScript, you can also write Angular 2 apps
|
|
in JavaScript and Dart by selecting either of those languages from the combo-box in the banner.
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## The shortest, quickest ...
|
|
|
|
Let's put something on the screen in Angular 2 as quickly as we can.
|
|
|
|
.l-sub-section
|
|
:markdown
|
|
While we are about to describe steps to take on your development machine,
|
|
you could take these same steps in an interactive, online coding environment
|
|
such as [plunker](http://plnkr.co/ "Plunker"). You won't have to
|
|
install a static server to run the app there.
|
|
|
|
If you like what you see - and we think you will - you can repeat this
|
|
exercise on your own machine later.
|
|
|
|
:markdown
|
|
**Create a new folder** to hold our application project, perhaps like this:
|
|
```
|
|
mkdir angular2-quickstart
|
|
cd angular2-quickstart
|
|
```
|
|
.l-main-section
|
|
:markdown
|
|
## Our first Angular component
|
|
|
|
**Add a new file** called **`app.ts`** and paste the following lines:
|
|
|
|
+makeExample('quickstart/ts/src/app/app.ts', null, 'app.ts')
|
|
|
|
:markdown
|
|
We've just defined an Angular 2 **component**,
|
|
one of the most important Angular 2 features.
|
|
Components are our primary means of creating application views
|
|
and supporting them with application logic.
|
|
|
|
Ours is an empty, do-nothing class class named `AppComponent`.
|
|
It would expand with properties and application
|
|
logic when we're ready to build a substantive application.
|
|
|
|
Above the class we see the `@Component` decoration.
|
|
|
|
.l-sub-section
|
|
:markdown
|
|
The `@` symbol before the method name identifies `Component` as a decoration.
|
|
A "decoration" is a TypeScript language feature
|
|
for creating metadata about the class. Angular finds this metadata
|
|
in the transpiled JavaScript and responds appropriately.
|
|
:markdown
|
|
`@Component` tells Angular that this class *is an Angular component*.
|
|
The configuration object passed to the `@Component` method has two
|
|
field, a `selector` and a `template`.
|
|
|
|
The `selector` specifies a CSS selector for a host HTML element named `my-app`.
|
|
Angular creates and displays an instance of our `AppComponent`
|
|
wherever it encounters a `my-app` element.
|
|
|
|
The `template` field is the component's companion template
|
|
that tells Angular how to render a view.
|
|
Our template is a single line of HTML announcing "My First Angular App".
|
|
|
|
The `bootstrap` method tells Angular to start the application with this
|
|
component at the application root.
|
|
We'd be correct to guess that someday our application will
|
|
consist of more components arising in tree-like fashion from this root.
|
|
|
|
In the top line we imported the `Component` and `bootstrap` symbols
|
|
from the Angular 2 library. That's the way we do things now.
|
|
We no longer expect to find our code or any library code in a global namespace.
|
|
We `import` exactly what we need, as we need it, from named file and library resources.
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## Add `index.html`
|
|
|
|
**Create** an `index.html` file.
|
|
|
|
**Paste** the following lines into it ... and we'll discuss them:
|
|
|
|
+makeExample('quickstart/ts/src/index.1.html', null, 'index.html')
|
|
|
|
:markdown
|
|
We see three noteworthy sections of HTML:
|
|
|
|
1. We load JavaScript libraries from the web.
|
|
Let's take them on faith without further discussion.<br/><br/>
|
|
|
|
2. We configure something called `System` and ask it to import the
|
|
application file with our `AppComponent` that we just wrote.
|
|
`System` is the module loader (from the `system.js` library),
|
|
a tool that can `import` code;
|
|
remember the `import` statement in our `AppComponent`?
|
|
|
|
We're also asking `system.js` to "transpile" (AKA "compile") our
|
|
TypeScript source code into JavaScript ... right here in the browser.<br/><br/>
|
|
|
|
3. We note the `<my-app>` tag in the `<body>`.
|
|
That's the custom HTML element we identified in the `@Component` decoration
|
|
adorning our `AppComponent` class.
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## Run it!
|
|
|
|
We need a static file server to serve our application to the browser.
|
|
|
|
.l-sub-section
|
|
:markdown
|
|
Don't have a static file server handy? Let's install one of our favorites
|
|
called [live-server](https://www.npmjs.com/package/live-server "Live-server")
|
|
with the **npm package manager**.
|
|
|
|
Don't have npm?
|
|
[Get it now](https://docs.npmjs.com/getting-started/installing-node "Installing Node.js and updating npm")
|
|
because we're going to use it now and repeatedly throughout this documentation.
|
|
|
|
Once you have `npm` installed, open a terminal window and enter
|
|
|
|
pre.prettyprint.lang-bash
|
|
code npm install -g live-server
|
|
|
|
:markdown
|
|
Open a terminal window and enter
|
|
|
|
pre.prettyprint.lang-bash
|
|
code live-server
|
|
:markdown
|
|
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")
|
|
|
|
:markdown
|
|
Congratulations! We are in business.
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## What's wrong with this?
|
|
|
|
We were up and running in a hurry and we could explore Angular
|
|
in this manner for quite some time.
|
|
|
|
For a number of reasons this isn't a good approach for building an application.
|
|
<!-- TODO The formatting here is a little weird. Should improve readability. -->
|
|
|
|
* Transpiling TypeScript in the browser becomes tediously slow when our
|
|
app grows beyond a few files. We certainly won't do that in production. We should learn to
|
|
compile locally and push the generated JavaScript to the server. We'll need some tools for that.
|
|
|
|
|
|
* Downloading JavaScript libraries from the web is OK for demos but
|
|
it slows our development. Every time our app reloads, it must refetch these libraries.
|
|
Don't count on browser caching.
|
|
Our debugging and live-reload techniques will bust the browser cache. Loading libraries
|
|
from the web also prevents us from developing our application offline or where connectivity is
|
|
poor. Let's learn to download the libraries to our machine and serve them locally.
|
|
|
|
|
|
* We want our development cycle to be as fast and friction-free as possible.
|
|
When we change our code, we want to see the results in the browser immediately.
|
|
We have tools and procedures for that.
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## Upping our game
|
|
Let's take a few more steps to put our development on a better foundation. We will
|
|
|
|
1. Revise the application project structure for future growth
|
|
1. Install a few tools and packages
|
|
1. Revise the **`index.html`** to use local library resources
|
|
1. Compile the TypeScript locally and watch for changes
|
|
|
|
Shut down the `live-server` running in the terminal window (Ctrl-C) and proceed as follows.
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## Revise the application project structure
|
|
|
|
At the moment we're dumping everything into the "angular2-quickstart" **root folder**.
|
|
Not bad when there are only two files. Not good as our application evolves.
|
|
|
|
Let's give our project a little structure.
|
|
|
|
We'll add a sub-folder - `src` - to hold project source code and a sub-sub-folder - `src/app` -
|
|
to hold the application source code.
|
|
|
|
In OS/X and Linux:
|
|
|
|
pre.prettyprint.lang-bash
|
|
code mkdir src/app
|
|
|
|
:markdown
|
|
In Windows:
|
|
|
|
pre.prettyprint.lang-bash
|
|
code mkdir src\app
|
|
|
|
:markdown
|
|
**Move `index.html`** into the **`src`** folder.
|
|
|
|
**Move `app.ts`** into the **`src/app`** folder.
|
|
|
|
Our project folders should look like this.
|
|
```
|
|
angular2-quickstart
|
|
└── src
|
|
├── app
|
|
│ └── app.ts
|
|
└── index.html
|
|
```
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## Install npm packages locally
|
|
|
|
We'll replace the web-based scripts in our `index.html` with
|
|
scripts resident on our local machine.
|
|
We get those scripts by installing two runtime `npm` packages into our project.
|
|
|
|
>**angular2** - the Angular 2 library.
|
|
|
|
>**systemjs** - an open-source library that provides module loading.
|
|
|
|
We'll also install two development tools:
|
|
|
|
>**typescript** - the TypeScript compiler
|
|
|
|
>**[live-server](https://www.npmjs.com/package/live-server "Live-server")** - the static file server that reloads the browser when files change.
|
|
We may have loaded it earlier. We're doing it again
|
|
locally in our project so we are no longer vulnerable to
|
|
a global uninstall or version change.
|
|
|
|
**Open** a terminal window at our application's **root folder**
|
|
|
|
Enter these commands:
|
|
```
|
|
npm init -y
|
|
npm i angular2@2.0.0-alpha.44 systemjs@0.19.2 --save --save-exact
|
|
npm i typescript live-server --save-dev
|
|
```
|
|
|
|
These commands both *install* the packages and *create* an npm `package.json` that will
|
|
help us develop and maintain our application in future.
|
|
The essence of our `package.json` should look like this:
|
|
|
|
+makeJson('quickstart/ts/package.json', { paths: 'name, version, dependencies, devDependencies'})
|
|
|
|
:markdown
|
|
There is also a `scripts` section. **Find and replace** it with the following:
|
|
|
|
+makeJson('quickstart/ts/package.json', { paths: 'scripts'})
|
|
|
|
:markdown
|
|
We've just extended our project world with script commands
|
|
that we'll be running very soon.
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## Update `index.html`
|
|
|
|
**Replace** the library scripts section with references to
|
|
scripts in the packages we just installed.
|
|
|
|
+makeExample('quickstart/ts/src/index.html', 'libraries')
|
|
|
|
:markdown
|
|
**Update** the `System` configuration script as follows.
|
|
|
|
+makeExample('quickstart/ts/src/index.html', 'systemjs')
|
|
|
|
.l-sub-section
|
|
:markdown
|
|
We won't be transpiling TypeScript in the browser anymore.
|
|
We'll do that on our machine and ship the generated JavaScript
|
|
files to the server.
|
|
|
|
We have to re-configure `system.js` to expect JavaScript files
|
|
with a `.js` extension by default.
|
|
Someday we might add a `Foo` class to our application in a `foo.ts`
|
|
file and import it like this
|
|
|
|
pre.prettyprint.lang-bash
|
|
code import {Foo} from './app/foo'
|
|
:markdown
|
|
`system.js`will know to look for a file named `foo.js` in the `src/app` folder.
|
|
|
|
That's exactly what we're doing in the last line. We're
|
|
importing our main application file `app` (the generated `app.js` to be precise)
|
|
from the `src/app/` folder (we moved it there, remember?)
|
|
:markdown
|
|
Here's the final version
|
|
|
|
+makeExample('quickstart/ts/src/index.html', null, 'index.html')
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## Prepare for TypeScript Compilation
|
|
|
|
### Add the TypeScript configuration file
|
|
|
|
We'll add a configuration file named **`tsconfig.json`**
|
|
to tell the editor how to interpret our TypeScript code and
|
|
to simplify the TypeScript compilation command that we'll run very soon.
|
|
|
|
**Change to the `src` folder and create a `tsconfig.json`** file with the following content:
|
|
+makeJson('quickstart/ts/src/tsconfig.json', null, 'tsconfig.json')
|
|
|
|
.alert.is-helpful
|
|
:markdown
|
|
See the [TypeScript configuration appendix](#tsconfig) to learn more about
|
|
this file and these settings.
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## Final structure
|
|
Our final project folder structure should look like this:
|
|
```
|
|
angular2-quickstart
|
|
├── node_modules
|
|
├── src
|
|
│ ├── app
|
|
| │ └── app.ts
|
|
│ ├── index.html
|
|
│ └── tsconfig.json
|
|
└── package.json
|
|
```
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## Compile the TypeScript to JavaScript
|
|
|
|
We no longer transpile TypeScript to JavaScript in the browser.
|
|
We run the **T**ype**S**cript **C**ompiler (TSC) on our machine instead.
|
|
|
|
Open a terminal window in the **root of the application folder** and enter:
|
|
|
|
pre.prettyprint.lang-bash
|
|
code npm run tsc
|
|
|
|
:markdown
|
|
When it's done we should find the generated *app.js* file in the *src* folder and also an *app.map.js* file that
|
|
helps debuggers navigate between the JavaScript and the TypeScript source.
|
|
|
|
Our script set the compiler watch option (`-w`) so the
|
|
compiler stays alive when it's finished.
|
|
It watches for changes to our **`.ts`** files
|
|
and recompiles them automatically.
|
|
|
|
Leave this command running in the terminal window.
|
|
You can stop it anytime with `Ctrl-C`.
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## Run the app!
|
|
|
|
Now we are ready to see our app in action.
|
|
|
|
Open another terminal window in the **root of the application folder** and
|
|
launch `live-server` again although this time we'll do it with
|
|
one of our `npm` script commands:
|
|
|
|
pre.prettyprint.lang-bash
|
|
code npm start
|
|
|
|
:markdown
|
|
**live-server** loads the browser for us, serves the HTML and JavaScript files,
|
|
and displays our application message once more:
|
|
|
|
figure.image-display
|
|
img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of quickstart app")
|
|
|
|
:markdown
|
|
### Make some changes
|
|
**`live-server`** detects changes to our files and refreshes the browser page for us automatically.
|
|
|
|
Try changing the message to "My SECOND Angular 2 app".
|
|
|
|
The TypeScript compiler in the first terminal window is watching our source code. It recompiles and produces
|
|
the revised *app.js*. The `live-server` sees that change and reloads the browser.
|
|
|
|
Keep `live-server` running in this terminal window. You can stop it anytime with `Ctrl-C`.
|
|
|
|
.l-main-section
|
|
:markdown
|
|
## What have we done?
|
|
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 added some JavaScript libraries to `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.**
|
|
|
|
We won't ask Angular to build "Hello, World".
|
|
We are asking it to help us build sophisticated applications with sophisticated requirements.
|
|
|
|
So we made some strategic technology investments to reach our larger goals
|
|
|
|
* our application loads faster with libraries installed locally and
|
|
we can develop offline if we wish.
|
|
|
|
* we're pre-compiling our TypeScript.
|
|
|
|
* we're running the compiler and live-server with commands that give us immediate feedback as we make changes.
|
|
|
|
The good news is that the overhead of setup is (mostly) behind us.
|
|
We're about to build a small application that demonstrates the great things
|
|
we can build with Angular 2.
|
|
|
|
<!--TODO: Join us on the [Tour of Heroes](./toh-pt1.html) -->
|
|
|
|
|
|
<!-- Move this to the Style Guide when we have one -->
|
|
.l-main-section
|
|
:markdown
|
|
<a id="tsconfig"></a>
|
|
### Appendix: TypeScript configuration
|
|
We added a TypeScript configuration file (`tsconfig.js`) to our project to
|
|
guide the compiler as it generates JavaScript files.
|
|
Get details about `tsconfig.js` from the official
|
|
[TypeScript wiki](https://github.com/Microsoft/TypeScript/wiki/tsconfig.json).
|
|
|
|
We'd like a moment to discuss the `noImplicitAny` flag.
|
|
TypeScript developers disagree about whether it should be `true` or `false`.
|
|
There is no correct answer and we can change the flag later.
|
|
But our choice now can make a difference in larger projects so it merits
|
|
discussion.
|
|
|
|
When the `noImplicitAny` flag is `false`,
|
|
the compiler silently defaults the type of a variable to `any` if it cannot infer
|
|
the type based on how the variable is used. That's what we mean by "implicitly `any`".
|
|
|
|
When the `noImplicitAny` flag is `true` and the TypeScript compiler cannot infer
|
|
the type, it still generates the JavaScript files but
|
|
it also reports an error.
|
|
|
|
For this project and the other examples in this Developer Guide
|
|
we set the `noImplicitAny` flag to `false`.
|
|
Developers who prefer stricter type checking should set the `noImplicitAny` flag to `true`.
|
|
We can still set a variable's type to `any` if
|
|
that seems like the best choice. We'd be doing so explicitly after
|
|
giving the matter some thought.
|
|
|
|
If we set the `noImplicitAny` flag to `true`, we may get implicit index errors as well.
|
|
If we feel these are more annoying than helpful,
|
|
we can suppress them with the following additional flag.
|
|
```
|
|
"suppressImplicitAnyIndexErrors":true
|
|
```
|