Merge branch 'master' into next

README.md

@@ -20,7 +20,7 @@ For the examples below, we assume we're in a project directory looking like this
 └── package.json
 ```
 
-All paths/routes are specified using [express syntax](http://expressjs.com/guide/routing.html#route-paths).
+All paths/routes are specified using [express syntax](http://expressjs.com/guide/routing.html#route-paths). To run the example projects linked below, clone the project, move into the example directory specified, run `ws`.
 
 ### Static site
 
@@ -30,6 +30,8 @@ $ ws
 serving at http://localhost:8000
 ```
 
+[Example](https://github.com/75lb/local-web-server/tree/master/example/simple).
+
 ### Single Page Application
 
 You're building a web app with client-side routing, so mark `index.html` as the SPA.
@@ -41,6 +43,8 @@ By default, typical SPA urls (e.g. `/user/1`, `/login`) would return `404 Not Fo
 
 *If a static file at the requested path exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then serve the specified SPA and handle the route client-side.*
 
+[Example](https://github.com/75lb/local-web-server/tree/master/example/spa).
+
 ### Access Control
 
 By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist:
@@ -49,6 +53,8 @@ $ ws --forbid '*.json' '*.yml'
 serving at http://localhost:8000
 ```
 
+[Example](https://github.com/75lb/local-web-server/tree/master/example/forbid).
+
 ### URL rewriting
 
 Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule:
@@ -86,6 +92,8 @@ Map local requests for repo data to the Github API:
 $ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name'
 ```
 
+[Example](https://github.com/75lb/local-web-server/tree/master/example/rewrite).
+
 ### Stored config
 
 Use the same port and blacklist every time? Persist it to `package.json`:
@@ -160,6 +168,8 @@ You can set additional mime-type/extension mappings, or override the defaults by
 }
 ```
 
+[Example](https://github.com/75lb/local-web-server/tree/master/example/mime-override).
+
 #### Log Visualisation
 Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/blob/master/doc/visualisation.md).
 
@@ -210,26 +220,61 @@ serving at http://localhost:8100
 
 ## API Reference
 
+
+* [local-web-server](#module_local-web-server)
+  * [localWebServer([options])](#exp_module_local-web-server--localWebServer) ⇒ <code>[KoaApplication](https://github.com/koajs/koa/blob/master/docs/api/index.md#application)</code> ⏏
+    * [~rewriteRule](#module_local-web-server--localWebServer..rewriteRule)
+
 <a name="exp_module_local-web-server--localWebServer"></a>
-### localWebServer([options]) ⏏
-Returns a Koa application
+### localWebServer([options]) ⇒ <code>[KoaApplication](https://github.com/koajs/koa/blob/master/docs/api/index.md#application)</code> ⏏
+Returns a Koa application you can launch or mix into an existing app.
 
 **Kind**: Exported function  
 **Params**
 - [options] <code>object</code> - options
-  - [.static] <code>object</code> - koajs/static config
+  - [.static] <code>object</code> - koa-static config
     - [.root] <code>string</code> - root directory
-    - [.options] <code>string</code> - options
+    - [.options] <code>string</code> - [options](https://github.com/koajs/static#options)
   - [.serveIndex] <code>object</code> - koa-serve-index config
     - [.path] <code>string</code> - root directory
-    - [.options] <code>string</code> - options
-  - [.forbid] <code>Array.&lt;string&gt;</code> - a list of forbidden routes.
+    - [.options] <code>string</code> - [options](https://github.com/expressjs/serve-index#options)
+  - [.forbid] <code>Array.&lt;string&gt;</code> - A list of forbidden routes, each route being an [express route-path](http://expressjs.com/guide/routing.html#route-paths).
+  - [.spa] <code>string</code> - specify an SPA file to catch requests for everything but static assets.
+  - [.log] <code>object</code> - [morgan](https://github.com/expressjs/morgan) config
+    - [.format] <code>string</code> - [log format](https://github.com/expressjs/morgan#predefined-formats)
+    - [.options] <code>object</code> - [options](https://github.com/expressjs/morgan#options)
+  - [.compress] <code>boolean</code> - Serve gzip-compressed resources, where applicable
+  - [.mime] <code>object</code> - A list of mime-type overrides, passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine)
+  - [.rewrite] <code>[Array.&lt;rewriteRule&gt;](#module_local-web-server--localWebServer..rewriteRule)</code> - One or more rewrite rules
+  - [.verbose] <code>boolean</code> - Print detailed output, useful for debugging
 
 **Example**  
 ```js
 const localWebServer = require('local-web-server')
 localWebServer().listen(8000)
 ```
+<a name="module_local-web-server--localWebServer..rewriteRule"></a>
+#### localWebServer~rewriteRule
+The `from` and `to` routes are specified using [express route-paths](http://expressjs.com/guide/routing.html#route-paths)
+
+**Kind**: inner typedef of <code>[localWebServer](#exp_module_local-web-server--localWebServer)</code>  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| from | <code>string</code> | request route |
+| to | <code>string</code> | target route |
+
+**Example**  
+```json
+{
+  "rewrite": [
+    { "from": "/css/*", "to": "/build/styles/$1" },
+    { "from": "/npm/*", "to": "http://registry.npmjs.org/$1" },
+    { "from": "/:user/repos/:name", "to": "https://api.github.com/repos/:user/:name" }
+  ]
+}
+```
 
 * * *
 

jsdoc2md/README.hbs

@@ -20,7 +20,7 @@ For the examples below, we assume we're in a project directory looking like this
 └── package.json
 ```
 
-All paths/routes are specified using [express syntax](http://expressjs.com/guide/routing.html#route-paths).
+All paths/routes are specified using [express syntax](http://expressjs.com/guide/routing.html#route-paths). To run the example projects linked below, clone the project, move into the example directory specified, run `ws`.
 
 ### Static site
 
@@ -30,6 +30,8 @@ $ ws
 serving at http://localhost:8000
 ```
 
+[Example](https://github.com/75lb/local-web-server/tree/master/example/simple).
+
 ### Single Page Application
 
 You're building a web app with client-side routing, so mark `index.html` as the SPA.
@@ -41,6 +43,8 @@ By default, typical SPA urls (e.g. `/user/1`, `/login`) would return `404 Not Fo
 
 *If a static file at the requested path exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then serve the specified SPA and handle the route client-side.*
 
+[Example](https://github.com/75lb/local-web-server/tree/master/example/spa).
+
 ### Access Control
 
 By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist:
@@ -49,6 +53,8 @@ $ ws --forbid '*.json' '*.yml'
 serving at http://localhost:8000
 ```
 
+[Example](https://github.com/75lb/local-web-server/tree/master/example/forbid).
+
 ### URL rewriting
 
 Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule:
@@ -86,6 +92,8 @@ Map local requests for repo data to the Github API:
 $ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name'
 ```
 
+[Example](https://github.com/75lb/local-web-server/tree/master/example/rewrite).
+
 ### Stored config
 
 Use the same port and blacklist every time? Persist it to `package.json`:
@@ -160,6 +168,8 @@ You can set additional mime-type/extension mappings, or override the defaults by
 }
 ```
 
+[Example](https://github.com/75lb/local-web-server/tree/master/example/mime-override).
+
 #### Log Visualisation
 Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/blob/master/doc/visualisation.md).
 

lib/cli-options.js

@@ -14,7 +14,7 @@ module.exports = {
     },
     {
       name: 'compress', alias: 'c', type: Boolean,
-      description: 'Enable gzip compression, reduces bandwidth.', group: 'server'
+      description: 'Serve gzip-compressed resources, where applicable', group: 'server'
     },
     {
       name: 'forbid', alias: 'b', type: String, multiple: true, typeLabel: '[underline]{path} ...',
@@ -26,7 +26,7 @@ module.exports = {
     },
     {
       name: 'rewrite', alias: 'r', type: String, multiple: true, typeLabel: '[underline]{expression} ...',
-      description: "A list of URL rewrite rules, e.g. '/from -> /to'", group: 'server'
+      description: "A list of URL rewrite rules. For each rule, separate the 'from' and 'to' routes with '->'. Whitespace surrounded the routes is ignored. E.g. '/from -> /to'", group: 'server'
     },
     {
       name: 'spa', alias: 's', type: String, typeLabel: '[underline]{file}',

lib/local-web-server.js

@@ -11,18 +11,27 @@ let debug
 module.exports = localWebServer
 
 /**
- * Returns a Koa application
+ * Returns a Koa application you can launch or mix into an existing app. 
  *
  * @param [options] {object} - options
- * @param [options.static] {object} - koajs/static config
+ * @param [options.static] {object} - koa-static config
  * @param [options.static.root] {string} - root directory
- * @param [options.static.options] {string} - options
+ * @param [options.static.options] {string} - [options](https://github.com/koajs/static#options)
  * @param [options.serveIndex] {object} - koa-serve-index config
  * @param [options.serveIndex.path] {string} - root directory
- * @param [options.serveIndex.options] {string} - options
- * @param [options.forbid] {string[]} - a list of forbidden routes.
+ * @param [options.serveIndex.options] {string} - [options](https://github.com/expressjs/serve-index#options)
+ * @param [options.forbid] {string[]} - A list of forbidden routes, each route being an [express route-path](http://expressjs.com/guide/routing.html#route-paths).
+ * @param [options.spa] {string} - specify an SPA file to catch requests for everything but static assets.
+ * @param [options.log] {object} - [morgan](https://github.com/expressjs/morgan) config
+ * @param [options.log.format] {string} - [log format](https://github.com/expressjs/morgan#predefined-formats)
+ * @param [options.log.options] {object} - [options](https://github.com/expressjs/morgan#options)
+ * @param [options.compress] {boolean} - Serve gzip-compressed resources, where applicable
+ * @param [options.mime] {object} - A list of mime-type overrides, passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine)
+ * @param [options.rewrite] {module:local-web-server~rewriteRule[]} - One or more rewrite rules
+ * @param [options.verbose] {boolean} - Print detailed output, useful for debugging
  *
  * @alias module:local-web-server
+ * @return {external:KoaApplication}
  * @example
  * const localWebServer = require('local-web-server')
  * localWebServer().listen(8000)
@@ -244,3 +253,27 @@ function mockResponses (options) {
 process.on('unhandledRejection', (reason, p) => {
   throw reason
 })
+
+/**
+ * The `from` and `to` routes are specified using [express route-paths](http://expressjs.com/guide/routing.html#route-paths)
+ *
+ * @example
+ * ```json
+ * {
+ *   "rewrite": [
+ *     { "from": "/css/*", "to": "/build/styles/$1" },
+ *     { "from": "/npm/*", "to": "http://registry.npmjs.org/$1" },
+ *     { "from": "/:user/repos/:name", "to": "https://api.github.com/repos/:user/:name" }
+ *   ]
+ * }
+ * ```
+ *
+ * @typedef rewriteRule
+ * @property from {string} - request route
+ * @property to {string} - target route
+ */
+
+/**
+ * @external KoaApplication
+ * @see https://github.com/koajs/koa/blob/master/docs/api/index.md#application
+ */

package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-web-server",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "description": "A simple web-server for productive front-end development",
   "bin": {
     "ws": "./bin/cli.js"