quickstart.jade

include _util-fns
  
:marked
  Our QuickStart goal is to build and run a super-simple Angular 2 application in TypeScript.

  ## See It Run!

  Try this <a href="/resources/live-examples/quickstart/ts/plnkr.html" target="_blank">live example</a>
  which loads the sample app in <a href="http://plnkr.co/" title="Plunker" target="_blank">plunker</a>
  and displays a simple message:

figure.image-display
  img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app")
:marked
  Of course we don't build apps to run in plunker.
  The following steps establish a development environment for the documentation samples
  that also can be the foundation for our real world applications. At a high level, we will
  
  - set up the [development environment](#devenv)
  - write the app's Angular [root component](#component)
  - write [main.ts](#main) which tells Angular to display the root component
  - write the [host web page](#index) (`index.html`)

.l-sub-section
  :marked
    We'll see many code blocks as we pursue this agenda. They're all easy to copy and paste:
  code-example(format='.', language='html').
    Click the glyph on the right to copy code snippets to the clipboard  ⇨⇨⇨⇨⇨⇨⇨⇨⇨⇨
    
button(class="verbose off md-primary md-button md-ink-ripple", type="button", onclick="verbose(false)").
  Hide explanations
button(class="verbose on md-primary md-button md-ink-ripple", type="button", onclick="verbose(true)").
  View explanations
.l-verbose-section
  :marked
    *Explanations* describe the concepts and reasons behind the instructions.
    Explanations have a thin border on the left like *this* block of text.
        
    Click *Hide Explanations* to show only the instructions. 
    Click it again to see everything again.

a(id="devenv")
.l-main-section
:marked
  ## Development Environment
  
  We need to set up our development environment: 
  * 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
  * install the npm packages and typings files
  
a(id="install-npm")
:marked
  **Install [node and npm](https://nodejs.org/en/download/)** if not already on your machine.
  
a(id="app-folder")
:marked
  Create a **new project folder**
code-example(format="").
  mkdir angular2-quickstart
  cd    angular2-quickstart
    
a(id="tsconfig")
:marked
  Add a **tsconfig.json** file to the project folder and copy/paste the following:
+makeJson('quickstart/ts/tsconfig.1.json', null, 'tsconfig.json')(format=".")

:marked
  This `tsconfig.json` file guides the TypeScript compiler.
  Learn more about it in the 
  <a href="guide/typescript-configuration.html#tsconfig" target="_blank">TypeScript Configuration</a> chapter.

a(id="typings")
:marked
  Add a **typings.json** file to the project folder and copy/paste the following:
+makeJson('quickstart/ts/typings.1.json', null, 'typings.json')(format=".")

.l-verbose-section
  :marked
    Many JavaScript libraries extend the JavaScript environment with features and syntax
    that the TypeScript compiler doesn't recognize natively. We teach it about these capabilities with
    <a href="http://www.typescriptlang.org/Handbook#writing-dts-files" 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 
    <a href="guide/typescript-configuration.html#typings" target="_blank">TypeScript Configuration</a> chapter.

a(id="package-json")
: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` - run the compiler and a server  at the same time, both in "watch mode"
    
    * `npm run tsc` - run the TypeScript compiler once
    
    * `npm run tsc:w` - run 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` - run the <a href="https://www.npmjs.com/package/lite-server" target="_blank">lite-server</a>, 
    a light-weight, static file server, written and maintained by 
    <a href="http://johnpapa.net/" target="_blank">John Papa</a> 
    with excellent support for Angular apps that use routing.
    
    * `npm run typings` - runs the [*typings* tool](#typings)
    
    * `npm postinstall` - called by *npm* automatically *after* it successfully completes package installation.
    This script installs the [TypeScript definition files](#typings) this app requires.

: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
      #### npm errors and warnings
      
      All is well if there are no console messages starting with `npm ERR!` *at the end* of **npm install**. 
      There might be a few `npm WARN` messages along the way &mdash; and that is perfectly fine.
      
      We often see an `npm WARN` message after a series of `gyp ERR!` messages. 
      Ignore them. A package may try to re-compile itself using `node-gyp`.
      If the re-compile fails, the package recovers (typically with a pre-built version)
      and everything works.
      
      Just make sure there are no `npm ERR!` messages at the end of `npm install`.

:marked
  **We're all set.** Let's write some code.


a(id="component")
.l-main-section
:marked
  ## Our First 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
code-example(format="").
  mkdir app
  cd    app

a(id="app-component")
:marked
  **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=".")
  
.l-verbose-section
  :marked
    ### AppComponent is the root of the application
    
    Every Angular app has at least one root component, conventionally named `AppComponent`,
    that hosts the client user experience.
    
    Components are the basic building blocks of Angular applications.
    A component controls a portion of the screen &mdash; a *view* &mdash; through its associated template.

    This QuickStart has only one, extremely simple component.
    But it has the essential structure of every component we'll ever write:
    
    * One or more <a href="javascript: why('component-import')">import</a>
    statements to reference the things we need.  
    
    * A <a href="javascript: why('decorator')">@Component decorator</a> 
    that tells Angular what template to use and how to create the component.
    
    * A <a href="javascript: why('class')">component class</a>
    that controls the appearance and behavior of a view through its template.
    
  a(id="component-import")
  :marked
    ### Import

    Angular apps are modular. They consist of many files each dedicated to a purpose.
          
    Angular itself is modular. It is a collection of library modules
    each made up of several, related features that we'll use to build our application.
    
    When we need something from a module, we import it. 
    Here we import the Angular `Component` decorator function from the
    main Angular library module because we need it to define our component.
  +makeExample('quickstart/ts/app/app.component.ts', 'import', 'app/app.component.ts (import)')(format=".")

  a(id="component-decorator")
  :marked
    ### @Component decorator

    `Component` is a **decorator** function that takes a *metadata* object.
    The metadata tell Angular how to create and use this component.
    
    We apply this function to the component class 
    by prefixing the function with the **@** symbol and invoking it with the metadata object.
    just above the class:
  +makeExample('quickstart/ts/app/app.component.ts', 'metadata', 'app/app.component.ts (metadata)')(format=".")
  :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 element for this component is named `my-app`.
    Angular creates and displays an instance of our `AppComponent`
    wherever it encounters a `my-app` element in the host HTML.

    The **template** specifies the component's companion template,
    written in an enhanced form of HTML that tells Angular how to render this component's view.
    
    >Our template is a single line of HTML announcing "*My First Angular App*".
    
    >A more advanced template could contain data bindings to component properties
    and might identify other application components which have their own templates.
    These templates might identify yet other components.
    In this way an Angular application becomes a tree of components.

  a(id="component-class")
  :marked
    ### Component class
    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=".")
  :marked
    When we're ready to build a substantive application, 
    we can expand this class with properties and application logic. 
    Our `AppComponent` class is empty because we don't need it to do anything in this QuickStart.
    
    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
:marked
  ## 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:
+makeExample('quickstart/ts/app/main.ts', null, 'app/main.ts')(format=".")

.l-verbose-section
  :marked
    We import the two things we need to launch the application:

    1. Angular's browser `bootstrap` function
    1. The application root component, `AppComponent`.
    
    Then we call `bootstrap` with `AppComponent`.
 
    ### Bootstrapping is platform-specific
    Notice that we import the `bootstrap` function from `angular2/platform/browser`,
    not `angular2/core`.
    
    Bootstrapping isn't core because there isn't a single way to bootstrap the app.
    True, most applications that run in a browser call the bootstrap function from
    this library.
      
    But it is possible to load a component in a different environment. 
    We might load it on a mobile device with [Apache Cordova](https://cordova.apache.org/) or [NativeScript](https://www.nativescript.org/).
    We might wish to render the first page of our application on the server
    to improve launch performance or facilitate 
    [SEO](http://static.googleusercontent.com/media/www.google.com/en//webmasters/docs/search-engine-optimization-starter-guide.pdf).

    These targets require a different kind of bootstrap function that we'd import from a different library.
  
    ### Why create a separate ***main.ts*** file?
    
    The *main.ts* file is tiny. This is just a QuickStart.
    We could have folded its few lines into the `app.component` file
    and spared ourselves some complexity.
    
    We'd rather demonstrate the proper way to structure an Angular application.
    App bootstrapping is a separate concern from presenting a view. 
    Mixing concerns creates difficulties down the road.
    We might launch the `AppComponent` in multiple environments with different bootstrappers. 
    Testing the component is much easier if it doesn't also try to run the entire application.
    Let's make the small extra effort to do it *the right way*.

a(id="index")
.l-main-section
:marked
  ## Add the `index.html`
  The `index.html` is the web page that hosts the application
  
  Navigate to the **project root folder**.
  
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 three noteworthy sections of HTML

    1. The JavaScript [libraries](#libraries)
    
    2. Configuration of [SystemJS](#systemjs) where we also import and run the
    `main` file that we just wrote.
    
    3. 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 Internet Explorer polyfills. 
    IE requires polyfills to run
    an application that relies on ES2015 promises and dynamic module loading.
    Most applications need those capabilities and most applications
    should run in Internet Explorer.

    Next are the polyfills for Angular2, `angular2-polyfills.js`.
    
    Then the [SystemJS](#systemjs) library for module loading,
    followed by the Reactive Extensions RxJS library.
  .l-sub-section
    :marked
      Our QuickStart doesn't use the Reactive Extensions 
      but any substantial application will want them
      when working with observables.
      We added the library here in QuickStart so we don't forget later.
  :marked
    Finally, we loaded the web development version of Angular 2 itself.

    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")
  :marked
    ### SystemJS Configuration

    The QuickStart uses <a href="https://github.com/systemjs/systemjs" target="_blank">SystemJS</a>
      to load application and library modules. 
    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?
  +makeExample('quickstart/ts/index.html', 'systemjs', 'index.html (System configuration)')(format=".")
  :marked
    The `packages` node tells SystemJS what to do when it sees a request for a 
    module from the `app/` folder. 
    
    Our QuickStart makes such requests when one of its
    application TypeScript files has an import statement like this:
  +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. 
    The `packages:` configuration tells 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
      #### 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. That's not our preference for development or production.
      
      We 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 problem 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")
  :marked
    ### *&lt;my-app&gt;*
    When Angular calls the `bootstrap` function in `main.ts`, it reads the `AppComponent`
    metadata, finds the `my-app` selector, locates an element tag named `my-app`,
    and loads our application between those tags.

.l-main-section
:marked
  ## Compile and run!
  
  Open a terminal window and enter this command:
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
  img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of quickstart app")

:marked
  Congratulations!  We are in business.

  ### Make some changes
  
  Try changing the message to "My SECOND Angular 2 app".
  
  The TypeScript compiler and `lite-server` are watching.
  They should detect the change, recompile the TypeScript into JavaScript,
  refresh the browser, and display the revised message.

  It's a nifty way to develop an application!
  
  We close the terminal window when we're done to terminate both the compiler and the server.

.l-main-section
:marked
  ## Final structure
  Our final project folder structure looks like this:
.filetree
  .file angular2-quickstart
  .children
    .file app
    .children
      .file app.component.ts
      .file main.ts
    .file node_modules ...
    .file typings ...
    .file index.html
    .file package.json
    .file tsconfig.json
    .file typings.json
:marked
  And here are the files:
+makeTabs(`
    quickstart/ts/app/app.component.ts,
    quickstart/ts/app/main.ts,
    quickstart/ts/index.html,
    quickstart/ts/package.1.json,
    quickstart/ts/tsconfig.1.json,
    quickstart/ts/typings.1.json
  `,null,
  `app/app.component.ts, app/main.ts, index.html,package.json, tsconfig.json, typings.json`)
:marked

.l-main-section
:marked
  ## Wrap Up
  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.**

  The good news is that the overhead of setup is (mostly) behind us. 
  We'll probably only touch the `package.json` to update libraries.
  We'll likely open `index.html` only if we need to add a library or some css stylesheets.

  We're about to take the next step and build a small application that 
  demonstrates the great things we can build with Angular 2.

  Join us on the [Tour of Heroes Tutorial](./tutorial)!