feat(prod-deploy): add prod deploy chapter

Author: filipesilva

public/docs/ts/latest/cookbook/_data.json

@@ -10,6 +10,11 @@
     "intro": "Learn how to use Ahead-of-time compilation"
   },
 
+  "production-deploy": {
+    "title": "Production Deploy",
+    "intro": "Learn how to deploy your Angular app to production"
+  },
+
   "a1-a2-quick-reference": {
     "title": "Angular 1 to 2 Quick Reference",
     "navTitle": "Angular 1 to 2 Quick Ref",

public/docs/ts/latest/cookbook/production-deploy.jade

@@ -0,0 +1,316 @@
+include ../_util-fns
+  
+:marked
+  This cookbook describes how to optimize and deploy your Angular app to production.
+
+a#toc
+:marked
+  ## Table of Contents
+  * [Overview](#overview)
+  * [Simplest deploy possible](#simplest-deploy-possible)
+  * [Minimizing your payload](#minimizing-your-payload)
+    * [Less files](#less-files)
+    * [Smaller files](#smaller-files)
+    * [Template compilation](#template-compilation)
+  * [Angular configuration](#angular-configuration)
+    * [The `base` tag](#the-base-tag)
+    * [enableProdMode](#enableprodmode)
+    * [Lazy loading](#lazy-loading)
+  * [Server configuration](#server-configuration)
+    * [Why fallback to `index.html`?](#why-fallback-to-index-html-)  
+    * [Fallback configuration examples](#fallback-configuration-examples)  
+
+a#overview
+.l-main-section
+:marked
+  ## Overview
+
+  After creating your brand new Angular app you'll want to put it online for the world to see.
+
+  Your development setup is optimized for build speed and rapid iteration, but when
+  deployment to production you'll want to optimize for loading speed and payload size.
+
+  In this chapter you'll see how to deploy your app right now, techniques to reduce your 
+  payload size, plus Angular and server configuration.
+
+.l-main-section
+:marked
+  ## Simplest deploy possible
+
+  The simplest possible way to deploy your app is to use your development environment.
+  It is already working locally after all, so it should work live.
+
+  1. Copy over your local project folder to your server.
+  2. In your server, edit `index.html` to have the right `<base href="/">` tag. If you are
+  using a subfolder (e.g. `www.mysite.com/myapp/`) it should be `/myapp/` otherwise leave it as `/`.
+  [More on this later](#angular-configuration).
+  3. Configure your server to redirect requests for missing files to `index.html` instead.
+  [More on this later](#server-configuration).
+
+  And this is all you need to publish your app!
+
+  It's not a very good production deploy though. 
+  There's more you can do to make our site fast for users.
+ 
+.l-main-section
+:marked
+  ## Minimizing your payload
+
+  One of the easiest optimizations you can do is to reduce the code users have to download.
+  
+  There are several techniques for achieving a smaller payload for your app:
+
+  - Bundling: concatenating several modules into a single file (bundle). 
+  - Inlining: add html and css as strings inside components.
+  - Minification: removing all unnecessary whitespace and optional tokens.
+  - Uglification: rewriting code to use shorter variable/function names.
+  - Dead Code Elimination: removing code/variables that will never used.
+  - Tree shaking: removing unused module exports.
+  - Ahead-of-Time (AoT) Compilation: pre-compiling Angular templates.
+
+  Each of these do different things overall, but they all work together and their effects
+  compound on each other.
+
+  ### Less files
+  Bundling and inlining reduce your app's load time smaller by serving less files and thus
+  less round trips. 
+  For small files, the overwhelming majority of time it takes to get it is not spent downloading,
+  but rather communicating with the server and coordinating the transfer. 
+  You can read more about resource timings in the 
+  [Chrome DevTools Network Performance page](https://developers.google.com/web/tools/chrome-devtools/network-performance/understanding-resource-timing)   
+
+  ### Smaller files
+  Minification, Uglification and Dead Code Elimination all contribute to reduce the total size
+  of your code to the smallest possible amount of bytes, which will result in a smaller
+  transfer time.
+
+  Tree shaking also reduces the total size but does so by removing whole exports from modules.
+  It was popularized by [Rollup](http://rollupjs.org/) and you can read more about it in 
+  [this post](https://medium.com/@Rich_Harris/tree-shaking-versus-dead-code-elimination-d3765df85c80#.15ih9cyvl).
+
+  ### Template compilation
+  AoT compilation reduces render time by pre-compiling Angular templates that otherwise would be
+  compiled at runtime. 
+  It also reduces payload size since the Angular compiler itself is no longer needed, and nor are
+  directives that are never used in templates. This allows Tree-Shaking to further remove exports.
+
+  You can read more about AoT Compilation in our [dedicated cookbook chapter](aot-compiler.html),
+  where you'll also find instructions on how to use Rollup to do all the optimizations shown here.
+  Another great choice is [Webpack 2](https://webpack.js.org/) together with the 
+  [Angular Ahead-of-Time Webpack Plugin](https://github.com/angular/angular-cli/tree/master/packages/%40ngtools/webpack).
+  
+  You can use any build system you like however, the only important thing is to optimize your build.
+  Whatever build system you choose make sure to automate it so that you can make a production
+  build in a single step.
+
+.l-main-section
+:marked
+  ## Angular configuration
+
+  ### The `base` tag
+
+  There is an important configuration item in the Angular Router that needs to be adjusted for 
+  different environments: 
+  [the `base` tags `href` property](https://angular.io/docs/ts/latest/guide/router.html#!#base-href).
+  This property tells the router how what the app root URL is so that the router can match routes.
+
+  On your development server, your app is most likely served at the root: `http://localhost:3000/`.
+  Here you use `<base href="/">`, since `/` is the root of your app.
+  
+  But depending on the server setup that you use, it can also be served in a subfolder like
+  `http://localhost:3000/myapp/` or `http://www.mysite.com/myapp/`, where `/myapp/` is the subfolder.
+  In this case you should use `<base href="/myapp/">`, since `/myapp/` is the root of your app and 
+  not `/`.
+
+  When your `base` tag is misconfigured your browser console will show several console, from
+  missing files on wrong paths to router errors about missing routes.
+
+  ### enableProdMode
+
+  You can also configure your Angular app to start on 
+  [production mode](https://angular.io/docs/ts/latest/api/core/index/enableProdMode-function.html), 
+  which will make it faster by disabling development specific checks.
+
+  Angular apps default do development move, as you can see by the following message on the browser
+  console:
+
+code-example(format="nocode").
+  Angular 2 is running in the development mode. Call enableProdMode() to enable the production mode.
+
+:marked
+  To enable production mode, add this code to the start of your `main.ts`:
+
+code-example().
+  import { enableProdMode } from '@angular/core';
+  enableProdMode();
+
+:marked
+  ### Lazy loading
+
+  The Angular Router allows you to configure NgModules as being 
+  [Lazy Loaded](https://angular.io/docs/ts/latest/guide/router.html#!#asynchronous-routing),
+  which means that particular NgModule (and all it's code) is not loaded on the very first load.
+  This allows your app to have a smaller initial load time by not loading modules until they
+  are needed.
+
+  A common mistake to make while lazy loading a module is to *also* have that module imported via
+  a ES6 import. 
+  If you do that, the module will never really be lazy loaded since the import statement will cause
+  it to be imported directly instead of being imported via the Router. 
+
+  It's important to note that your bundling configuration must take lazy loading into consideration.
+  Since there is no ES6 import for that module, normal bundlers don't know that they should also
+  separately bundle to module listed in the router config.
+  You have to manually create additional bundles for each lazy loaded route.
+
+  If you are using Webpack, the 
+  [Angular Ahead-of-Time Webpack Plugin](https://github.com/angular/angular-cli/tree/master/packages/%40ngtools/webpack)
+  will automatically recognize lazy routes.
+
+
+.l-main-section
+:marked
+  ## Server configuration
+
+  Angular apps are 
+  [Single Page Applications](https://en.wikipedia.org/wiki/Single-page_application) (SPAs),
+  which makes them the perfect candidates to be served by simple static HTML server.
+  No preprocessors required!
+
+  There is only one configuration item required of a server hosting an Angular app:
+  it needs to be able to fallback to `index.html` when being asked for a file the server
+  does not have.
+
+  ### Why fallback to `index.html`?
+
+  When using the Angular Router, it is the one in charge of the routing instead of your server.
+  Angular routing defaults to 
+  [HTML 5 pushState](https://angular.io/docs/ts/latest/guide/router.html#!#browser-url-styles),
+  where it manipulates the browser address and history directly.
+  So, while the server has the responsability of serving the files, it is always the Angular app
+  that will determine which routes are valid and construct the page accordingly.
+  
+  Imagine you have the `admin/` route for your `www.my-awesome-app.com` Angular app. 
+  When you visit `www.my-awesome-app.com` most servers will respond with
+  the `index.html` located at `www.my-awesome-app.com/index.html`. 
+  Then you click the link for `admin/` and the your address bar will change 
+  to `www.my-awesome-app.com/admin/` and you're taken to the admin page.
+
+  But if you don't have fallback to `index.html` configured and refresh the page, you will
+  get a `404 - Not Found` page!
+  Which doesn't make a lot of sense since you just saw that the admin page was there.
+
+  When you first clicked the link to `admin/` there was no server request for 
+  `www.my-awesome-app.com/admin/` because Angular manipulated the browser URL directly.
+
+  But when you refresh the `www.my-awesome-app.com/admin/` url, you are not asking *Angular*
+  for the admin route but rather *the server*.
+  And the server does not have a `www.my-awesome-app.com/admin/index.html` to serve, so it instead
+  shows you a 404.
+
+  That is why the server needs to be configured to fallback to `index.html`.
+  When a user asks the server for any route (that isn't a file), you want the server to *always*
+  return default page that boots up Angular.
+  After Angular is loaded and bootstrapped the router will look at the address bar and take
+  the user where he needs to go.
+
+  ### Fallback configuration examples
+
+  Different servers are configured in different ways so there is no single configuration that
+  works everywhere.
+
+  Following are configurations for some of the most popular servers. 
+  The list is by no means exhausting, but should provide you with a good starting point.
+
+  #### Development servers
+  
+  - [Lite-Server](https://github.com/johnpapa/lite-server): the default dev server used in the
+  [Quickstart repo](https://github.com/angular/quickstart), and by default will fallback to 
+  `index.html`.
+
+  - [Webpack-Dev-Server](https://github.com/webpack/webpack-dev-server): you can use the 
+  `historyApiFallback` entry in the dev server options as follows:
+
+code-example().
+  historyApiFallback: {
+    disableDotRule: true,
+    htmlAcceptHeaders: ['text/html', 'application/xhtml+xml']
+  }
+
+:marked
+  #### Production servers
+  
+  - [Apache](https://httpd.apache.org/): simply add a 
+  [rewrite rule](http://httpd.apache.org/docs/current/mod/mod_rewrite.html)
+  to your `.htaccess` file as show 
+  [here](https://ngmilk.rocks/2015/03/09/angularjs-html5-mode-or-pretty-urls-on-apache-using-htaccess/):
+code-example(format=".").
+  RewriteEngine On  
+  # If an existing asset or directory is requested go to it as it is
+  RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR]
+  RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d
+  RewriteRule ^ - [L]
+
+  # If the requested resource doesn't exist, use index.html
+  RewriteRule ^ /index.html
+
+:marked
+  - [NGinx](http://nginx.org/): you can use `try_files` similar to the one described in 
+  [Front Controller Pattern Web Apps](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#front-controller-pattern-web-apps),
+  modified for serving `index.html`:
+
+code-example(format=".").
+  try_files $uri $uri/ /index.html;
+
+:marked
+  - [IIS](https://www.iis.net/): you can add a rewrite rule on `web.config`, similar to the one shown
+  [here](http://stackoverflow.com/a/26152011/2116927):
+code-example(format="." escape="html").
+  <system.webServer>
+    <rewrite>
+      <rules>
+        <rule name="Angular Routes" stopProcessing="true">
+          <match url=".*" />
+          <conditions logicalGrouping="MatchAll">
+            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
+            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
+          </conditions>
+          <action type="Rewrite" url="/" />
+        </rule>
+      </rules>
+    </rewrite>
+  </system.webServer>
+
+:marked
+  - [GitHub Pages](https://pages.github.com/): you can't 
+  [directly configure](https://github.com/isaacs/github/issues/408) 
+  the server used to serve GitHub Pages, but you can add a 404 page. 
+  Simply copy `index.html` into `404.html`.
+  It will still be served with the 404 response, but the app will still load properly.
+  It's also a good idea to 
+  [serve from `docs/` on master](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch) 
+  and to 
+  [create a `.nojekyll` file](https://www.bennadel.com/blog/3181-including-node-modules-and-vendors-folders-in-your-github-pages-site.htm)
+  
+  - [Firebase hosting](https://firebase.google.com/docs/hosting/): you can use a simple 
+  [rewrite](https://firebase.google.com/docs/hosting/url-redirects-rewrites#section-rewrites).
+
+code-example(format=".").
+  "rewrites": [ {
+    "source": "**",
+    "destination": "/index.html"
+  } ]
+
+:marked
+  ### CORS
+  
+  A common issue developers come across when working on SPAs is 
+  [Cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
+  errors.
+  These are not due to the SPA application itself but rather due to the configuration of APIs with
+  which the SPA communicates.
+
+  These APIs need to send the `Access-Control-Allow-Origin: *` header on their HTTP responses,
+  otherwise the SPA will not be able to call them.
+  You can read more about how to enable CORS for specific servers in 
+  [enable-cors.org](http://enable-cors.org/server.html)