angular-cn/public/docs/ts/latest/quickstart.jade

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-getting-started
    cd    angular2-getting-started
    ```

    ## Our first Angular component

    **Add a new file** called **`app.ts`** and paste the following lines:

  +makeExample('gettingstarted/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`, `View`, and `bootstrap` methods
    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.

    ## Add `index.html`

    **Create** an `index.html` file.

    **Paste** the following lines into it ... and we'll discuss them:

  +makeExample('gettingstarted/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.

    ## 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/getting-started/my-first-app.png' alt="Output of getting started 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-getting-started" **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-getting-started
    └── 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.42 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('gettingstarted/ts/package.json', { paths: 'name, version, dependencies, devDependencies'})

  :markdown
    There is also a `scripts` section. **Find and replace** it with the following:

  +makeJson('gettingstarted/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('gettingstarted/ts/src/index.html', 'libraries')

  :markdown
    **Update** the `System` configuration script as follows.

  +makeExample('gettingstarted/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('gettingstarted/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('gettingstarted/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-getting-started
    ├── 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/getting-started/my-first-app.png' alt="Output of getting started 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) -->


<!-- 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
    ```