docs(@angular/cli): document serving the app from disk

Closes angular#4290 Close angular#5308
asnowwolf · Mar 16, 2017 · d91a2ad · d91a2ad
1 parent 91bedda
commit d91a2ad
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 1 deletion.
diff --git a/docs/documentation/serve.md b/docs/documentation/serve.md
@@ -24,4 +24,7 @@ All the build Options are available in serve below are the additional options.
 
 `--ssl-cert` SSL certificate to use for serving HTTPS.
 
-`--ssl-key` SSL key to use for serving HTTPS.
+`--ssl-key` SSL key to use for serving HTTPS.
+
+## Note
+When running `ng serve`, the compiled output is served from memory, not from disk. This means that the application being served is not located on disk in the `dist` folder.
diff --git a/docs/documentation/stories.md b/docs/documentation/stories.md
@@ -20,3 +20,4 @@
  - [Routing](stories/routing)
  - [3rd Party Lib](stories/third-party-lib)
  - [Corporate Proxy](stories/using-corporate-proxy)
+ - [Serve from Disk](stories/disk-serve)
diff --git a/docs/documentation/stories/disk-serve.md b/docs/documentation/stories/disk-serve.md
@@ -0,0 +1,23 @@
+# Serve from Disk
+
+The CLI supports running a live browser reload experience to users by running `ng serve`. This will compile the application upon file saves and reload the browser with the newly compiled application. This is done by hosting the application in memory and serving it via [webpack-dev-server](https://webpack.js.org/guides/development/#webpack-dev-server).
+
+If you wish to get a similar experience with the application output to disk please use the steps below. This practice will allow you to ensure that serving the contents of your `dist` dir will be closer to how your application will behave when it is deployed.
+
+## Environment Setup
+### Install a web server
+You will not be using webpack-dev-server, so you will need to install a web server for the browser to request the application. There are many to choose from but a good one to try is [lite-server](https://github.com/johnpapa/lite-server) as it will auto-reload your browser when new files are output.
+
+## Usage
+You will need two terminals to get the live-reload experience. The first will run the build in a watch mode to compile the application to the `dist` folder. The second will run the web server against the `dist` folder. The combination of these two processes will mimic the same behavior of ng serve.
+
+### 1st terminal - Start the build
+```bash
+ng build --watch
+```
+
+### 2nd terminal - Start the web server
+```bash
+lite-server --baseDir="dist"
+```
+When using `lite-server` the default browser will open to the appropriate URL.