docs

README.md

@@ -1,5 +1,6 @@
 [![view on npm](http://img.shields.io/npm/v/local-web-server.svg)](https://www.npmjs.org/package/local-web-server)
-[![npm module downloads per month](http://img.shields.io/npm/dm/local-web-server.svg)](https://www.npmjs.org/package/local-web-server)
+[![npm module downloads](http://img.shields.io/npm/dt/local-web-server.svg)](https://www.npmjs.org/package/local-web-server)
+[![Build Status](https://travis-ci.org/75lb/local-web-server.svg?branch=master)](https://travis-ci.org/75lb/local-web-server)
 [![Dependency Status](https://david-dm.org/75lb/local-web-server.svg)](https://david-dm.org/75lb/local-web-server)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/feross/standard)
 
@@ -8,6 +9,31 @@ A static web-server for productive front-end development.
 
 **Requires node v4.0.0 or higher**.
 
+## Synopsis
+
+From the folder you wish to serve, run:
+```sh
+$ ws
+serving at http://localhost:8000
+```
+
+If you wish to serve a different directory, run:
+```sh
+$ ws -d ~/mysite/
+serving /Users/Lloyd/mysite at http://localhost:8000
+```
+
+If you wish to override the default port (8000), use `--port` or `-p`:
+```sh
+$ ws --port 9000
+serving at http://localhost:9000
+```
+
+To add compression, reducing bandwidth, increasing page load time (by 10-15% on my Macbook Air)
+```sh
+$ ws --compress
+```
+
 ## Install
 Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`.
 
@@ -45,50 +71,6 @@ $ npm install
 $ npm start
 ```
 
-## Usage
-```
-Usage
-$ ws <server options>
-$ ws --config
-$ ws --help
-
-Server
--p, --port <number>           Web server port
--f, --log-format <string>     If a format is supplied an access log is written to stdout. If not, a statistics view is displayed. Use a
-                              preset ('none', 'dev','combined', 'short', 'tiny' or 'logstalgia') or supply a custom format (e.g. ':method ->
-                              :url').
--d, --directory <string>      Root directory, defaults to the current directory
--c, --compress                Enable gzip compression, reduces bandwidth.
--r, --refresh-rate <number>   Statistics view refresh rate in ms. Defaults to 500.
-
-Misc
--h, --help                    Print these usage instructions
---config                      Print the stored config
-```
-
-From the folder you wish to serve, run:
-```sh
-$ ws
-serving at http://localhost:8000
-```
-
-If you wish to serve a different directory, run:
-```sh
-$ ws -d ~/mysite/
-serving /Users/Lloyd/mysite at http://localhost:8000
-```
-
-If you wish to override the default port (8000), use `--port` or `-p`:
-```sh
-$ ws --port 9000
-serving at http://localhost:9000
-```
-
-To add compression, reducing bandwidth, increasing page load time (by 10-15% on my Macbook Air)
-```sh
-$ ws --compress
-```
-
 ### Logging
 Passing a value to `--log-format` will write an access log to `stdout`.
 
@@ -154,40 +136,27 @@ You can set additional mime-type/extension mappings, or override the defaults by
 }
 ```
 
-## Use with Logstalgia
+## Log Visualisation
-local-web-server is compatible with [logstalgia](http://code.google.com/p/logstalgia/).
+Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/wiki/Log-visualisation).
 
-### Install Logstalgia
+# API Reference
-On MacOSX, install with [homebrew](http://brew.sh):
-```sh
-$ brew install logstalgia
-```
 
-Alternatively, [download a release for your system from github](https://github.com/acaudwell/Logstalgia/releases/latest).
+<a name="module_local-web-server"></a>
+## local-web-server
+<a name="exp_module_local-web-server--localWebServer"></a>
+### localWebServer([options]) ⏏
+Returns a Koa application
 
-Then pipe the `logstalgia` output format directly into logstalgia for real-time visualisation:
+**Kind**: Exported function  
-```sh
-$ ws -f logstalgia | logstalgia -
-```
 
-![local-web-server with logstalgia](http://75lb.github.io/local-web-server/logstagia.gif)
+| Param | Type | Description |
+| --- | --- | --- |
+| [options] | <code>object</code> | options |
+| [options.blacklist] | <code>Array.&lt;regexp&gt;</code> | a list of forbidden routes. |
 
-## Use with glTail
+**Example**  
-To use with [glTail](http://www.fudgie.org), write your log to disk using the "default" format:
+```js
-```sh
+const localWebServer = require('local-web-server')
-$ ws -f default > web.log
-```
-
-Then specify this file in your glTail config:
-
-```yaml
-servers:
-    dev:
-        host: localhost
-        source: local
-        files: /Users/Lloyd/Documents/MySite/web.log
-        parser: apache
-        color: 0.2, 0.2, 1.0, 1.0
 ```
 
 * * *

bin/cli.js

@@ -9,49 +9,45 @@ const cliOptions = require('../lib/cli-options')
 const loadConfig = require('config-master')
 const path = require('path')
 
-const options = {}
-
-/* parse command line args */
 const cli = commandLineArgs(cliOptions.definitions)
 const usage = cli.getUsage(cliOptions.usageData)
+const stored = loadConfig('local-web-server')
+const options = collectOptions()
 
-try {
+if (options.misc.help) {
-  options.cli = cli.parse()
+  console.log(usage)
-} catch (err) {
+  process.exit(0)
-  halt(err.message)
 }
-
+if (options.misc.config) {
-options.stored = loadConfig('local-web-server')
+  console.log(JSON.stringify(stored, null, '  '))
-
+  process.exit(0)
-
-options.builtIn = {
-  port: 8000,
-  root: process.cwd(), // root dir when using multiple static dirs
-  directory: process.cwd(),
-  proxyRoutes: [],
-  blacklist: []
 }
 
-/* override built-in defaults with stored config and then command line args */
-options.cli.server = Object.assign(options.builtIn, options.stored, options.cli.server)
-
-if (options.cli.misc.help) return console.log(usage)
-if (options.cli.misc.config) return console.log(JSON.stringify(options.stored, null, '  '))
-
 localWebServer({
-  static: { root: options.cli.server.directory },
+  static: {
-  serveIndex: { path: options.cli.server.directory, options: { icons: true } },
+    root: options.server.directory,
-  log: { format: options.cli.server['log-format'] },
+    options: {
-  compress: options.cli.server.compress,
+      hidden: true
-  mime: options.cli.server.mime,
+    }
-  blacklist: options.cli.server.blacklist.map(regexp => RegExp(regexp, "i")),
+  },
-  proxyRoutes: options.cli.server.proxyRoutes,
+  serveIndex: {
-  spa: options.cli.server.spa,
+    path: options.server.directory,
-  'no-cache': options.cli.server['no-cache']
+    options: {
-}).listen(options.cli.server.port, onServerUp)
+      icons: true,
+      hidden: true
+    }
+  },
+  log: { format: options.server['log-format'] },
+  compress: options.server.compress,
+  mime: options.server.mime,
+  blacklist: options.server.blacklist.map(regexp => RegExp(regexp, "i")),
+  proxyRoutes: options.server.proxyRoutes,
+  spa: options.server.spa,
+  'no-cache': options.server['no-cache']
+}).listen(options.server.port, onServerUp)
 
-function halt (message) {
+function halt (err) {
-  console.log(ansi.format(`Error: ${message}`, 'red'))
+  console.log(ansi.format(`Error: ${err.stack}`, 'red'))
   console.log(usage)
   process.exit(1)
 }
@@ -60,8 +56,31 @@ function onServerUp () {
   const e = Date.now()
   const time = `${e-s}ms`
   console.error(ansi.format(
-    path.resolve(options.cli.server.directory) === process.cwd()
+    path.resolve(options.server.directory) === process.cwd()
-      ? `serving at [underline]{http://localhost:${options.cli.server.port}} ${time}`
+      ? `serving at [underline]{http://localhost:${options.server.port}} ${time}`
-      : `serving [underline]{${options.cli.server.directory}} at [underline]{http://localhost:${options.cli.server.port}} ${time}`
+      : `serving [underline]{${options.server.directory}} at [underline]{http://localhost:${options.server.port}} ${time}`
   ))
 }
+
+function collectOptions () {
+  let options = {}
+
+  /* parse command line args */
+  try {
+    options = cli.parse()
+  } catch (err) {
+    halt(err)
+  }
+
+  const builtIn = {
+    port: 8000,
+    root: process.cwd(), // root dir when using multiple static dirs
+    directory: process.cwd(),
+    proxyRoutes: [],
+    blacklist: []
+  }
+
+  /* override built-in defaults with stored config and then command line args */
+  options.server = Object.assign(builtIn, stored, options.server)
+  return options
+}

jsdoc2md/README.hbs

@@ -0,0 +1,148 @@
+[![view on npm](http://img.shields.io/npm/v/local-web-server.svg)](https://www.npmjs.org/package/local-web-server)
+[![npm module downloads](http://img.shields.io/npm/dt/local-web-server.svg)](https://www.npmjs.org/package/local-web-server)
+[![Build Status](https://travis-ci.org/75lb/local-web-server.svg?branch=master)](https://travis-ci.org/75lb/local-web-server)
+[![Dependency Status](https://david-dm.org/75lb/local-web-server.svg)](https://david-dm.org/75lb/local-web-server)
+[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/feross/standard)
+
+# local-web-server
+A static web-server for productive front-end development.
+
+**Requires node v4.0.0 or higher**.
+
+## Synopsis
+
+From the folder you wish to serve, run:
+```sh
+$ ws
+serving at http://localhost:8000
+```
+
+If you wish to serve a different directory, run:
+```sh
+$ ws -d ~/mysite/
+serving /Users/Lloyd/mysite at http://localhost:8000
+```
+
+If you wish to override the default port (8000), use `--port` or `-p`:
+```sh
+$ ws --port 9000
+serving at http://localhost:9000
+```
+
+To add compression, reducing bandwidth, increasing page load time (by 10-15% on my Macbook Air)
+```sh
+$ ws --compress
+```
+
+## Install
+Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`.
+
+### Globally
+```sh
+$ npm install -g local-web-server
+```
+
+### Bundled with your project
+```sh
+$ npm install local-web-server --save-dev
+```
+
+Then add an `start` script to your `package.json` (the standard npm approach):
+```json
+{
+  "name": "my-web-app",
+  "version": "1.0.0",
+  "scripts": {
+    "start": "ws"
+  }
+}
+```
+This simplifies a rather specific-looking instruction set like:
+
+```sh
+$ npm install
+$ npm install -g local-web-server
+$ ws
+```
+
+to the following, server implementation and launch details abstracted away:
+```sh
+$ npm install
+$ npm start
+```
+
+### Logging
+Passing a value to `--log-format` will write an access log to `stdout`.
+
+Either use a built-in [morgan](https://github.com/expressjs/morgan) logger preset:
+```sh
+$ ws --log-format short
+```
+
+Or a custom [morgan](https://github.com/expressjs/morgan) log format:
+```sh
+$ ws -f ':method -> :url'
+```
+
+Or silence:
+```sh
+$ ws -f none
+```
+
+## Storing default options
+To store per-project options, saving you the hassle of inputting them everytime, store them in the `local-web-server` property of your project's `package.json`:
+```json
+{
+  "name": "my-project",
+  "version": "0.11.8",
+  "local-web-server":{
+    "port": 8100
+  }
+}
+```
+
+Or in a `.local-web-server.json` file stored in the directory you want to serve (typically the root folder of your site):
+```json
+{
+  "port": 8100,
+  "log-format": "tiny"
+}
+```
+
+Or store global defaults in a `.local-web-server.json` file in your home directory.
+```json
+{
+  "port": 3000,
+  "refresh-rate": 1000
+}
+```
+
+All stored defaults are overriden by options supplied at the command line.
+
+To view your stored defaults, run:
+
+```sh
+$ ws --config
+```
+
+## mime-types
+You can set additional mime-type/extension mappings, or override the defaults by setting a `mime` value in your local config. This value is passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine). Example:
+
+```json
+{
+    "mime": {
+        "text/plain": [ "php", "pl" ]
+    }
+}
+```
+
+## Log Visualisation
+Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/wiki/Log-visualisation).
+
+# API Reference
+
+{{>main}}
+
+* * *
+
+&copy; 2015 Lloyd Brookes <75pound@gmail.com>

lib/cli-options.js

@@ -18,7 +18,7 @@ module.exports = {
     },
     {
       name: 'no-cache', alias: 'n', type: Boolean,
-      description: 'Disable etag-based caching.', group: 'server'
+      description: 'Disable etag-based caching - forces loading from disk each request.', group: 'server'
     },
     {
       name: 'help', alias: 'h', type: Boolean,

lib/local-web-server.js

@@ -21,9 +21,18 @@ const send = require('koa-send')
 /**
  * @module local-web-server
  */
-module.exports = getApp
+module.exports = localWebServer
 
-function getApp (options) {
+/**
+ * Returns a Koa application
+ *
+ * @param [options] {object} - options
+ * @param [options.blacklist] {regexp[]} - a list of forbidden routes.
+ * @alias module:local-web-server
+ * @example
+ * const localWebServer = require('local-web-server')
+ */
+function localWebServer (options) {
   options = Object.assign({
     static: {},
     serveIndex: {},

package.json

@@ -22,7 +22,8 @@
     "node": ">=4.0.0"
   },
   "scripts": {
-    "test": "tape test/*.js"
+    "test": "tape test/*.js",
+    "docs": "jsdoc2md -t jsdoc2md/README.hbs lib/*.js > README.md; echo"
   },
   "repository": "https://github.com/75lb/local-web-server",
   "author": "Lloyd Brookes <75pound@gmail.com>",