diff --git a/aio/content/guide/build.md b/aio/content/guide/build.md
new file mode 100644
index 0000000000..39cb3b3661
--- /dev/null
+++ b/aio/content/guide/build.md
@@ -0,0 +1,536 @@
+# Building and serving Angular apps
+
+*intro - here are some topics of interest in the app development cycle*
+
+{@a app-environments}
+
+## Configuring application environments
+
+You can define different named build configurations for your project, such as *stage* and *production*, with different defaults.
+
+Each named build configuration can have defaults for any of the options that apply to the various build targets, such as `build`, `serve`, and `test`. The CLI `build`, `serve`, and `test` commands can then replace files with appropriate versions for your intended target environment.
+
+The following figure shows how a project has multiple build targets, which can be executed using the named configurations that you define.
+
+
+
+
+
+### Configure environment-specific defaults
+
+A project's `src/environments/` folder contains the base configuration file, `environment.ts`, which provides a default environment.
+You can add override defaults for additional environments, such as production and staging, in target-specific configuration files.
+
+For example:
+
+```
+└──myProject/src/environments/
+ └──environment.ts
+ └──environment.prod.ts
+ └──environment.stage.ts
+```
+
+The base file `environment.ts`, contains the default environment settings. For example:
+
+
+export const environment = {
+ production: false
+};
+
+
+The `build` command uses this as the build target when no environment is specified.
+You can add further variables, either as additional properties on the environment object, or as separate objects.
+For example, the following adds a default for a variable to the default environment:
+
+```
+export const environment = {
+ production: false,
+ apiUrl: 'http://my-api-url'
+};
+```
+
+You can add target-specific configuration files, such as `environment.prod.ts`.
+The following sets content sets default values for the production build target:
+
+```
+export const environment = {
+ production: true
+ apiUrl: 'http://my-prod-url'
+};
+```
+
+### Using environment-specific variables in your app
+
+The following application structure configures build targets for production and staging environments:
+
+```
+└── src
+ └── app
+ ├── app.component.html
+ └── app.component.ts
+ └── environments
+ ├── environment.prod.ts
+ ├── environment.staging.ts
+ └── environment.ts
+```
+
+To use the environment configurations you have defined, your components must import the original environments file:
+
+```
+import { environment } from './../environments/environment';
+```
+
+This ensures that the build and serve commands can find the configurations for specific build targets.
+
+The following code in the component file (`app.component.ts`) uses an environment variable defined in the configuration files.
+
+```
+import { Component } from '@angular/core';
+import { environment } from './../environments/environment';
+
+@Component({
+ selector: 'app-root',
+ templateUrl: './app.component.html',
+ styleUrls: ['./app.component.css']
+})
+export class AppComponent {
+ constructor() {
+ console.log(environment.production); // Logs false for default environment
+ }
+ title = 'app works!';
+}
+```
+{@a file-replacement}
+
+## Configure target-specific file replacements
+
+The main CLI configuration file, `angular.json`, contains a `fileReplacements` section in the configuration for each build target, which allows you to replace any file with a target-specific version of that file.
+This is useful for including target-specific code or variables in a build that targets a specific environment, such as production or staging.
+
+By default no files are replaced.
+You can add file replacements for specific build targets.
+For example:
+
+```
+"configurations": {
+ "production": {
+ "fileReplacements": [
+ {
+ "replace": "src/environments/environment.ts",
+ "with": "src/environments/environment.prod.ts"
+ }
+ ],
+ ...
+```
+
+This means that when you build your production configuration (using `ng build --prod` or `ng build --configuration=production`), the `src/environments/environment.ts` file is replaced with the target-specific version of the file, `src/environments/environment.prod.ts`.
+
+You can add additional configurations as required. To add a staging environment, create a copy of `src/environments/environment.ts` called `src/environments/environment.staging.ts`, then add a `staging` configuration to `angular.json`:
+
+```
+"configurations": {
+ "production": { ... },
+ "staging": {
+ "fileReplacements": [
+ {
+ "replace": "src/environments/environment.ts",
+ "with": "src/environments/environment.staging.ts"
+ }
+ ]
+ }
+}
+```
+
+You can add more configuration options to this target environment as well.
+Any option that your build supports can be overridden in a build target configuration.
+
+To build using the staging configuration, run `ng build --configuration=staging`.
+
+You can also configure the `serve` command to use the targeted build configuration if you add it to the "serve:configurations" section of `angular.json`:
+
+```
+"serve": {
+ "builder": "@angular-devkit/build-angular:dev-server",
+ "options": {
+ "browserTarget": "your-project-name:build"
+ },
+ "configurations": {
+ "production": {
+ "browserTarget": "your-project-name:build:production"
+ },
+ "staging": {
+ "browserTarget": "your-project-name:build:staging"
+ }
+ }
+},
+```
+
+{@a size-budgets}
+
+## Configure size budgets
+
+As applications grow in functionality, they also grow in size.
+The CLI allows you to set size thresholds in your configuration to ensure that parts of your application stay within size boundaries that you define.
+
+Define your size boundaries in the CLI configuration file, `angular.json`, in a `budgets` section for each [configured environment](#app-environments).
+
+```
+{
+ ...
+ "configurations": {
+ "production": {
+ ...
+ budgets: []
+ }
+ }
+}
+```
+
+You can specify size budgets for the entire app, and for particular parts.
+Each budget entry configures a budget of a given type.
+Specify size values in the following formats:
+
+* 123 or 123b: Size in bytes
+
+* 123kb: Size in kilobytes
+
+* 123mb: Size in megabytes
+
+* 12%: Percentage of size relative to baseline. (Not valid for baseline values.)
+
+When you configure a budget, the build system warns or reports and error when a given part of the app reaches or exceeds a boundary size that you set.
+
+Each budget entry is a JSON object with the following properties:
+
+
+
+
Property
+
Value
+
+
+
+
type
+
The type of budget. One of:
+
+ * bundle - The size of a specific bundle.
+ * initial - The initial size of the app.
+ * allScript - The size of all scripts.
+ * all - The size of the entire app.
+ * anyScript - The size of any one script.
+ * any - The size of any file.
+
+
+
+
+
name
+
+
+ The name of the bundle (for `type=bundle`).
+
+
+
+
+
baseline
+
An absolute baseline size for percentage values.
+
+
+
maximumWarning
+
Warns when a size exceeds this threshold percentage of the baseline.
+
+
+
maximumError
+
Reports an error when the size exceeds this threshold percentage of the baseline.
+
+
+
minimumWarning
+
Warns when the size reaches this threshold percentage of the baseline.
+
+
+
minimumError
+
Reports an error when the size reaches this threshold percentage of the baseline.
+
+
+
warning
+
Warns when the size ??reaches or exceeds?? this threshold percentage of the baseline.
+
+
+
error
+
Reports an error when the size ??reaches or exceeds?? this threshold percentage of the baseline.
+
+
+
+
+{@a assets}
+
+## Adding project assets
+
+You can configure your project with a set of assets, such as images, to copy directly into the build for a particular build target.
+
+Each build target section of the CLI configuration file, `angular.json`, has an `assets` section that lists files or folders you want to copy into the build for that target.
+By default, the `src/assets/` folder and `src/favicon.ico` are copied into a build.
+
+```
+"assets": [
+ "src/assets",
+ "src/favicon.ico"
+]
+```
+
+You can edit the assets configuration to extend it for assets outside your project.
+For example, the following invokes the [node-glob pattern matcher](https://github.com/isaacs/node-glob) using input from a given base folder.
+It sends output to a folder that is relative to `outDir`, a configuration value that defaults to `dist/`*project-name*).
+The result in this cased is the same as for the default assets configuration.
+
+```
+"assets": [
+ { "glob": "**/*", "input": "src/assets/", "output": "/assets/" },
+ { "glob": "favicon.ico", "input": "/src", "output": "/" },
+]
+```
+
+You can use this extended configuration to copy assets from outside your project.
+For instance, you can copy assets from a node package with the following value:
+
+```
+"assets": [
+ { "glob": "**/*", "input": "./node_modules/some-package/images", "output": "/some-package/" },
+]
+```
+
+This makes the contents of `node_modules/some-package/images/` available in the output folder `dist/some-package/`.
+
+
+
+ For reasons of security, the CLI never writes files outside of the project output path.
+
+
+
+{@a browser-compat}
+
+## Configuring browser compatibility
+
+The CLI uses [Autoprefixer](https://github.com/postcss/autoprefixer) to ensure compatibility with different browser and browser versions.
+You may find it necessary to target specific browsers or exclude certain browser versions from your build.
+
+Internally, Autoprefixer relies on a library called [Browserslist(https://github.com/ai/browserslist)] to figure out which browsers to support with prefixing.
+Browserlist looks for configuration options in a `browserlist` property of the package configuration file, or in a configuration file named `.browserslistrc`.
+Autoprefixer looks for the Browserlist configuration when it prefixes your CSS.
+
+* You can tell Autoprefixer what browsers to target by adding a browserslist property to the package configuration file, `package.json`:
+```
+ "browserslist": [
+ "> 1%",
+ "last 2 versions"
+ ]
+```
+
+* Alternatively, you can add a new file, `.browserslistrc`, to the project directory, that specifies browsers you want to support:
+```
+ ### Supported Browsers
+ > 1%
+ last 2 versions
+```
+
+See the [browserslist repo](https://github.com/ai/browserslist) for more examples of how to target specific browsers and versions.
+
+
>
+Backward compatibility
+
+If you want to produce a progressive web app and are using [Lighthouse](https://developers.google.com/web/tools/lighthouse/) to grade the project, add the following browserslist entry to your `package.json` file, in order to eliminate the [old flexbox](https://developers.google.com/web/tools/lighthouse/audits/old-flexbox) prefixes:
+
+```
+"browserslist": [
+ "last 2 versions",
+ "not ie <= 10",
+ "not ie_mob <= 10"
+]
+```
+
+
+
+{@a proxy}
+
+## Proxying to a backend server
+
+You can use the [proxying support](https://webpack.js.org/configuration/dev-server/#devserver-proxy) in the `webpack` dev server to divert certain URLs to a backend server, by passing a file to the `--proxy-config` build option.
+For example, to divert all calls for http://localhost:4200/api to a server running on http://localhost:3000/api, take the following steps.
+
+1. Create a file `proxy.conf.json` in the projects `src/` folder, next to `package.json`.
+
+1. Add the following content to the new proxy file:
+ ```
+ {
+ "/api": {
+ "target": "http://localhost:3000",
+ "secure": false
+ }
+ }
+ ```
+
+1. In the CLI configuration file, `angular.json`, add the `proxyConfig` option to the `serve` target:
+ ```
+ ...
+ "architect": {
+ "serve": {
+ "builder": "@angular-devkit/build-angular:dev-server",
+ "options": {
+ "browserTarget": "your-application-name:build",
+ "proxyConfig": "src/proxy.conf.json"
+ },
+ ...
+ ```
+
+1. To run the dev server with this proxy configuration, call `ng serve`.
+
+You can edit the proxy configuration file to add configuration options; some examples are given below.
+For a description of all options, see [webpack DevServer documentation](https://webpack.js.org/configuration/dev-server/#devserver-proxy).
+
+Note that if you edit the proxy configuration file, you must relaunch the `ng serve` process to make your changes effective.
+
+### Rewrite the URL path
+
+The `pathRewrite` proxy configuration option lets you rewrite the URL path at run time.
+For example, you can specify the following `pathRewrite` value to the proxy configuration to remove "api" from the end of a path.
+
+```
+{
+ "/api": {
+ "target": "http://localhost:3000",
+ "secure": false,
+ "pathRewrite": {
+ "^/api": ""
+ }
+ }
+}
+```
+
+If you need to access a backend that is not on `localhost`, set the `changeOrigin` option as well. For example:
+
+```
+{
+ "/api": {
+ "target": "http://npmjs.org",
+ "secure": false,
+ "pathRewrite": {
+ "^/api": ""
+ },
+ "changeOrigin": true
+ }
+}
+```
+
+To help determine whether your proxy is working as intended, set the `logLevel` option. For example:
+
+```
+{
+ "/api": {
+ "target": "http://localhost:3000",
+ "secure": false,
+ "pathRewrite": {
+ "^/api": ""
+ },
+ "logLevel": "debug"
+ }
+}
+```
+
+Proxy log levels are `info` (the default), `debug`, `warn`, `error`, and `silent`.
+
+### Proxy multiple entries
+
+You can proxy multiple entries to the same target by defining the configuration in JavaScript.
+
+Set the proxy configuration file to `proxy.conf.js` (instead of `proxy.conf.json`), and specify configuration files as in the following example.
+
+```
+const PROXY_CONFIG = [
+ {
+ context: [
+ "/my",
+ "/many",
+ "/endpoints",
+ "/i",
+ "/need",
+ "/to",
+ "/proxy"
+ ],
+ target: "http://localhost:3000",
+ secure: false
+ }
+]
+
+module.exports = PROXY_CONFIG;
+```
+
+In the CLI configuration file, `angular.json`, point to the JavaScript proxy configuration file:
+
+```
+...
+"architect": {
+ "serve": {
+ "builder": "@angular-devkit/build-angular:dev-server",
+ "options": {
+ "browserTarget": "your-application-name:build",
+ "proxyConfig": "src/proxy.conf.js"
+ },
+...
+```
+
+### Bypass the proxy
+
+If you need to optionally bypass the proxy, or dynamically change the request before it's sent, add the bypass option, as shown in this JavaScript example.
+
+```
+const PROXY_CONFIG = {
+ "/api/proxy": {
+ "target": "http://localhost:3000",
+ "secure": false,
+ "bypass": function (req, res, proxyOptions) {
+ if (req.headers.accept.indexOf("html") !== -1) {
+ console.log("Skipping proxy for browser request.");
+ return "/index.html";
+ }
+ req.headers["X-Custom-Header"] = "yes";
+ }
+ }
+}
+
+module.exports = PROXY_CONFIG;
+```
+
+### Using corporate proxy
+
+If you work behind a corporate proxy, the cannot directly proxy calls to any URL outside your local network.
+In this case, you can configure the backend proxy to redirect calls through your corporate proxy using an agent:
+
+
+npm install --save-dev https-proxy-agent
+
+
+When you define an environment variable `http_proxy` or `HTTP_PROXY`, an agent is automatically added to pass calls through your corporate proxy when running `npm start`.
+
+Use the following content in the JavaScript configuration file.
+
+```
+var HttpsProxyAgent = require('https-proxy-agent');
+var proxyConfig = [{
+ context: '/api',
+ target: 'http://your-remote-server.com:3000',
+ secure: false
+}];
+
+function setupForCorporateProxy(proxyConfig) {
+ var proxyServer = process.env.http_proxy || process.env.HTTP_PROXY;
+ if (proxyServer) {
+ var agent = new HttpsProxyAgent(proxyServer);
+ console.log('Using corporate proxy server: ' + proxyServer);
+ proxyConfig.forEach(function(entry) {
+ entry.agent = agent;
+ });
+ }
+ return proxyConfig;
+}
+
+module.exports = setupForCorporateProxy(proxyConfig);
+```
+
diff --git a/aio/content/guide/deployment.md b/aio/content/guide/deployment.md
index 95e3799a2f..0890cf930e 100644
--- a/aio/content/guide/deployment.md
+++ b/aio/content/guide/deployment.md
@@ -1,6 +1,7 @@
# Deployment
-This page describes techniques for deploying your Angular application to a remote server.
+When you are ready to deploy your Angular application to a remote server, you have various options for
+deployment. You may need to configure
{@a dev-deploy}
{@a copy-files}
@@ -18,27 +19,214 @@ For the simplest deployment, build for development and copy the output directory
2. Copy _everything_ within the output folder (`dist/` by default) to a folder on the server.
-
-3. If you copy the files into a server _sub-folder_, append the build flag, `--base-href` and set the `` appropriately.
-
- For example, if the `index.html` is on the server at `/my/app/index.html`, set the _base href_ to
- `` like this.
-
-
- ng build --base-href=/my/app/
-
-
- You'll see that the `` is set properly in the generated `dist/index.html`.
- If you copy to the server's root directory, omit this step and leave the `` alone.
- Learn more about the role of `` [below](guide/deployment#base-tag).
-
-
-4. Configure the server to redirect requests for missing files to `index.html`.
+3. Configure the server to redirect requests for missing files to `index.html`.
Learn more about server-side redirects [below](guide/deployment#fallback).
-
This is _not_ a production deployment. It's not optimized and it won't be fast for users.
-It might be good enough for sharing your progress and ideas internally with managers, teammates, and other stakeholders.
+It might be good enough for sharing your progress and ideas internally with managers, teammates, and other stakeholders. For the next steps in deployment, see [Optimize for production](#optimize).
+
+{@a deploy-to-github}
+
+## Deploy to GitHub pages
+
+Another simple way to deploy your Angular app is to use [GitHub Pages](https://help.github.com/articles/what-is-github-pages/).
+
+1. You will need to [create a GitHub account](https://github.com/join) if you don't have one, then [create a repository](https://help.github.com/articles/create-a-repo/) for your project.
+Make a note of the user name and project name in GitHub.
+
+1. Build your project using Github project name, with the following CLI command:
+
+ ng build --prod --output-path docs --base-href
+
+
+1. When the build is complete, make a copy of `docs/index.html` and name it `docs/404.html`.
+
+1. Commit your changes and push.
+
+1. On the GitHub project page, configure it to [publish from the docs folder](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).
+
+You can see your deployed page at `https://.github.io//`.
+
+
+ng build --watch
+
+
+1. Start the web server in terminal B:
+
+lite-server --baseDir="dist"
+
+The default browser opens to the appropriate URL.
+
+* [Lite-Server](https://github.com/johnpapa/lite-server): the default dev server installed with the
+[Quickstart repo](https://github.com/angular/quickstart) is pre-configured to fallback to `index.html`.
+
+* [Webpack-Dev-Server](https://github.com/webpack/webpack-dev-server): setup the
+`historyApiFallback` entry in the dev server options as follows:
+
+
+ historyApiFallback: {
+ disableDotRule: true,
+ htmlAcceptHeaders: ['text/html', 'application/xhtml+xml']
+ }
+
+
+#### Production servers
+
+* [Apache](https://httpd.apache.org/): add a
+[rewrite rule](http://httpd.apache.org/docs/current/mod/mod_rewrite.html) to the `.htaccess` file as shown
+ (https://ngmilk.rocks/2015/03/09/angularjs-html5-mode-or-pretty-urls-on-apache-using-htaccess/):
+
+
+ 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
+
+
+
+* [Nginx](http://nginx.org/): use `try_files`, as described in
+[Front Controller Pattern Web Apps](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#front-controller-pattern-web-apps),
+modified to serve `index.html`:
+
+
+ try_files $uri $uri/ /index.html;
+
+
+
+* [IIS](https://www.iis.net/): add a rewrite rule to `web.config`, similar to the one shown
+[here](http://stackoverflow.com/a/26152011/2116927):
+
+
+ <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="/index.html" />
+ </rule>
+ </rules>
+ </rewrite>
+ </system.webServer>
+
+
+
+
+* [GitHub Pages](https://pages.github.com/): you can't
+[directly configure](https://github.com/isaacs/github/issues/408)
+the GitHub Pages server, but you can add a 404 page.
+Copy `index.html` into `404.html`.
+It will still be served as the 404 response, but the browser will process that page and load the app 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/): add a
+[rewrite rule](https://firebase.google.com/docs/hosting/url-redirects-rewrites#section-rewrites).
+
+
+ "rewrites": [ {
+ "source": "**",
+ "destination": "/index.html"
+ } ]
+
+
+
+{@a cors}
+
+### Requesting services from a different server (CORS)
+
+Angular developers may encounter a
+
+cross-origin resource sharing error when making a service request (typically a data service request)
+to a server other than the application's own host server.
+Browsers forbid such requests unless the server permits them explicitly.
+
+There isn't anything the client application can do about these errors.
+The server must be configured to accept the application's requests.
+Read about how to enable CORS for specific servers at
+enable-cors.org.
+
+
{@a optimize}
@@ -65,14 +253,8 @@ The `--prod` _meta-flag_ engages the following optimization features.
The remaining [copy deployment steps](#copy-files) are the same as before.
-You may further reduce bundle sizes by adding the `build-optimizer` flag.
-
-
- ng build --prod --build-optimizer
-
-
-See the [CLI Documentation](https://github.com/angular/angular-cli/wiki/build)
-for details about available build options and what they do.
+See [Building and serving Angular apps](guide/build)
+for more about about CLI build options and what they do.
{@a enable-prod-mode}
@@ -102,22 +284,24 @@ Configure the Angular Router to defer loading of all other modules (and their as
or by [_lazy loading_](guide/router#asynchronous-routing "Lazy loading")
them on demand.
-#### Don't eagerly import something from a lazy loaded module
+
` to the se
When the `base` tag is mis-configured, the app fails to load and the browser console displays `404 - Not Found` errors
for the missing files. Look at where it _tried_ to find those files and adjust the base tag appropriately.
-## _build_ vs. _serve_
+## Building and serving for deployment
-You'll probably prefer `ng build` for deployments.
+When you are designing and developing applications, you typically use `ng serve` to build your app for fast, local, iterative development.
+When you are ready to deploy, however, you must use the `ng build` command to build the app and deploy the build artifacts elsewhere.
-The **ng build** command is intended for building the app and deploying the build artifacts elsewhere.
-The **ng serve** command is intended for fast, local, iterative development.
-
-Both `ng build` and `ng serve` **clear the output folder** before they build the project.
-The `ng build` command writes generated build artifacts to the output folder.
-The `ng serve` command does not.
-It serves build artifacts from memory instead for a faster development experience.
+Both `ng build` and `ng serve` clear the output folder before they build the project, but only the `build` command writes the generated build artifacts to the output folder.
@@ -222,160 +401,13 @@ To output to a different folder, change the `outputPath` in `angular.json`.
-The `ng serve` command builds, watches, and serves the application from a local CLI development server.
+The`serve` command builds, watches, and serves the application from local memory, using a local development server.
+When you have deployed your app to another server, however, you might still want to serve the app so that you can continue to see changes that you make in it.
+You can do this by adding the `--watch` option to the `build` command.
-The `ng build` command generates output files just once and does not serve them.
-The `ng build --watch` command will regenerate output files when source files change.
-This `--watch` flag is useful if you're building during development and
-are automatically re-deploying changes to another server.
+```
+ng build --watch
+```
+Like the `serve` command, this regenerates output files when source files change.
-
-See the [CLI `build` topic](https://github.com/angular/angular-cli/wiki/build) for more details and options.
-
-
-
-{@a server-configuration}
-
-## Server configuration
-
-This section covers changes you may have make to the server or to files deployed to the server.
-
-{@a fallback}
-
-### Routed apps must fallback to `index.html`
-
-Angular apps are perfect candidates for serving with a simple static HTML server.
-You don't need a server-side engine to dynamically compose application pages because
-Angular does that on the client-side.
-
-If the app uses the Angular router, you must configure the server
-to return the application's host page (`index.html`) when asked for a file that it does not have.
-
-{@a deep-link}
-
-
-A routed application should support "deep links".
-A _deep link_ is a URL that specifies a path to a component inside the app.
-For example, `http://www.mysite.com/heroes/42` is a _deep link_ to the hero detail page
-that displays the hero with `id: 42`.
-
-There is no issue when the user navigates to that URL from within a running client.
-The Angular router interprets the URL and routes to that page and hero.
-
-But clicking a link in an email, entering it in the browser address bar,
-or merely refreshing the browser while on the hero detail page —
-all of these actions are handled by the browser itself, _outside_ the running application.
-The browser makes a direct request to the server for that URL, bypassing the router.
-
-A static server routinely returns `index.html` when it receives a request for `http://www.mysite.com/`.
-But it rejects `http://www.mysite.com/heroes/42` and returns a `404 - Not Found` error *unless* it is
-configured to return `index.html` instead.
-
-#### Fallback configuration examples
-
-There is no single configuration that works for every server.
-The following sections describe configurations for some of the most popular servers.
-The list is by no means exhaustive, but should provide you with a good starting point.
-
-#### Development servers
-
-* [Lite-Server](https://github.com/johnpapa/lite-server): the default dev server installed with the
-[Quickstart repo](https://github.com/angular/quickstart) is pre-configured to fallback to `index.html`.
-
-
-* [Webpack-Dev-Server](https://github.com/webpack/webpack-dev-server): setup the
-`historyApiFallback` entry in the dev server options as follows:
-
-
- historyApiFallback: {
- disableDotRule: true,
- htmlAcceptHeaders: ['text/html', 'application/xhtml+xml']
- }
-
-
-
-#### Production servers
-
-* [Apache](https://httpd.apache.org/): add a
-[rewrite rule](http://httpd.apache.org/docs/current/mod/mod_rewrite.html) to the `.htaccess` file as shown
- (https://ngmilk.rocks/2015/03/09/angularjs-html5-mode-or-pretty-urls-on-apache-using-htaccess/):
-
-
- 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
-
-
-
-* [NGinx](http://nginx.org/): use `try_files`, as described in
-[Front Controller Pattern Web Apps](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#front-controller-pattern-web-apps),
-modified to serve `index.html`:
-
-
- try_files $uri $uri/ /index.html;
-
-
-
-* [IIS](https://www.iis.net/): add a rewrite rule to `web.config`, similar to the one shown
-[here](http://stackoverflow.com/a/26152011/2116927):
-
-
- <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="/index.html" />
- </rule>
- </rules>
- </rewrite>
- </system.webServer>
-
-
-
-
-* [GitHub Pages](https://pages.github.com/): you can't
-[directly configure](https://github.com/isaacs/github/issues/408)
-the GitHub Pages server, but you can add a 404 page.
-Copy `index.html` into `404.html`.
-It will still be served as the 404 response, but the browser will process that page and load the app 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/): add a
-[rewrite rule](https://firebase.google.com/docs/hosting/url-redirects-rewrites#section-rewrites).
-
-
- "rewrites": [ {
- "source": "**",
- "destination": "/index.html"
- } ]
-
-
-
-{@a cors}
-
-### Requesting services from a different server (CORS)
-
-Angular developers may encounter a
-
-cross-origin resource sharing error when making a service request (typically a data service request)
-to a server other than the application's own host server.
-Browsers forbid such requests unless the server permits them explicitly.
-
-There isn't anything the client application can do about these errors.
-The server must be configured to accept the application's requests.
-Read about how to enable CORS for specific servers at
-enable-cors.org.
+For complete details of the CLI commands and configuration options, see the *CLI Reference (link TBD)*.
diff --git a/aio/content/guide/file-structure.md b/aio/content/guide/file-structure.md
new file mode 100644
index 0000000000..d5f0470003
--- /dev/null
+++ b/aio/content/guide/file-structure.md
@@ -0,0 +1,382 @@
+# Workspace and project file structure
+
+An Angular CLI project is the foundation for both quick experiments and enterprise solutions. The CLI command `ng new` creates an Angular workspace in your file system that is the root for new projects, which can be apps and libraries.
+
+## Workspaces and project files
+
+Angular 6 introduced the [workspace](guide/glossary#workspace) directory structure for Angular [projects](guide/glossary#project). A project can be a standalone *application* or a *library*, and a workspace can contain multiple applications, as well as libraries that can be used in any of the apps.
+
+The CLI command `ng new my-workspace` creates a workspace folder and generates a new app skeleton in an `app` folder within that workspace.
+Within the `app/` folder, a `src/` subfolder contains the logic, data, and assets.
+A newly generated `app/` folder contains the source files for a root module, with a root component and template.
+
+The `app/` folder also contains project-specific configuration files, end-to-end tests, and the Angular system modules.
+
+```
+ my-workspace/
+ app/
+ e2e/
+ src/
+ node_modules/
+ src/
+```
+
+When this workspace file structure is in place, you can use the `ng generate` command on the command line to add functionality and data to the initial app.
+
+
ng new sassyproject --style=sass
+> ng new scss-project --style=scss
+> ng new less-project --style=less
+> ng new styl-project --style=styl
+```
+
+You can also set the default style for an existing project by configuring `@schematics/angular`,
+the default schematic for the Angular CLI:
+
+```
+> ng config schematics.@schematics/angular:component.styleext scss
+```
+
+#### Style configuration
+
+By default, the `styles.css` configuration file lists CSS files that supply global styles for a project.
+If you are using another style type, there is a similar configuration file for global style files of that type,
+with the extension for that style type, such as `styles.sass`.
+
+You can add more global styles by configuring the build options in the `angular.json` configuration file.
+List the style files in the "styles" section in your project's "build" target
+The files are loaded exactly as if you had added them in a `` tag inside `index.html`.
+
+```
+"architect": {
+ "build": {
+ "builder": "@angular-devkit/build-angular:browser",
+ "options": {
+ "styles": [
+ "src/styles.css",
+ "src/more-styles.css",
+ ],
+ ...
+```
+
+If you need the styles in your unit tests, add them to the "styles" option in the "test" target configuration as well.
+
+You can specify styles in an object format to rename the output and lazy load it:
+
+```
+"styles": [
+ "src/styles.css",
+ "src/more-styles.css",
+ { "input": "src/lazy-style.scss", "lazy": true },
+ { "input": "src/pre-rename-style.scss", "bundleName": "renamed-style" },
+],
+```
+
+In Sass and Stylus you can make use of the `includePaths` functionality for both component and global styles,
+which allows you to add extra base paths to be checked for imports.
+To add paths, use the `stylePreprocessorOptions` build-target option:
+
+```
+"stylePreprocessorOptions": {
+ "includePaths": [
+ "src/style-paths"
+ ]
+},
+```
+
+You can then import files in the given folder (such as `src/style-paths/_variables.scss`)
+anywhere in your project without the need for a relative path:
+
+```
+// src/app/app.component.scss
+// A relative path works
+@import '../style-paths/variables';
+// But now this works as well
+@import 'variables';
+```
+
+#### CSS preprocessor integration
+
+To use a supported CSS preprocessor, add the URL for the preprocessor
+to your component's `styleUrls` in the `@Component()` metadata.
+For example:
+
+```
+@Component({
+ selector: 'app-root',
+ templateUrl: './app.component.html',
+ styleUrls: ['./app.component.scss']
+})
+export class AppComponent {
+ title = 'app works!';
+}
+```
+
+
+