diff --git a/README.md b/README.md index 3fb7bcf..a022494 100644 --- a/README.md +++ b/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 -$ ws --config -$ ws --help - -Server --p, --port Web server port --f, --log-format 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 Root directory, defaults to the current directory --c, --compress Enable gzip compression, reduces bandwidth. --r, --refresh-rate 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 -local-web-server is compatible with [logstalgia](http://code.google.com/p/logstalgia/). +## 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). -### Install Logstalgia -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). +# API Reference -Then pipe the `logstalgia` output format directly into logstalgia for real-time visualisation: -```sh -$ ws -f logstalgia | logstalgia - -``` + +## local-web-server + +### localWebServer([options]) ⏏ +Returns a Koa application -![local-web-server with logstalgia](http://75lb.github.io/local-web-server/logstagia.gif) - -## Use with glTail -To use with [glTail](http://www.fudgie.org), write your log to disk using the "default" format: -```sh -$ ws -f default > web.log -``` +**Kind**: Exported function -Then specify this file in your glTail config: +| Param | Type | Description | +| --- | --- | --- | +| [options] | object | options | +| [options.blacklist] | Array.<regexp> | a list of forbidden routes. | -```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 +**Example** +```js +const localWebServer = require('local-web-server') ``` * * * diff --git a/bin/cli.js b/bin/cli.js index 93499d4..89fd8ea 100755 --- a/bin/cli.js +++ b/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 { - options.cli = cli.parse() -} catch (err) { - halt(err.message) +if (options.misc.help) { + console.log(usage) + process.exit(0) } - -options.stored = loadConfig('local-web-server') - - -options.builtIn = { - port: 8000, - root: process.cwd(), // root dir when using multiple static dirs - directory: process.cwd(), - proxyRoutes: [], - blacklist: [] +if (options.misc.config) { + console.log(JSON.stringify(stored, null, ' ')) + process.exit(0) } -/* 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 }, - serveIndex: { path: options.cli.server.directory, options: { icons: true } }, - log: { format: options.cli.server['log-format'] }, - compress: options.cli.server.compress, - mime: options.cli.server.mime, - blacklist: options.cli.server.blacklist.map(regexp => RegExp(regexp, "i")), - proxyRoutes: options.cli.server.proxyRoutes, - spa: options.cli.server.spa, - 'no-cache': options.cli.server['no-cache'] -}).listen(options.cli.server.port, onServerUp) + static: { + root: options.server.directory, + options: { + hidden: true + } + }, + serveIndex: { + path: options.server.directory, + options: { + 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) { - console.log(ansi.format(`Error: ${message}`, 'red')) +function halt (err) { + 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() - ? `serving at [underline]{http://localhost:${options.cli.server.port}} ${time}` - : `serving [underline]{${options.cli.server.directory}} at [underline]{http://localhost:${options.cli.server.port}} ${time}` + path.resolve(options.server.directory) === process.cwd() + ? `serving at [underline]{http://localhost:${options.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 +} diff --git a/jsdoc2md/README.hbs b/jsdoc2md/README.hbs new file mode 100644 index 0000000..87d1515 --- /dev/null +++ b/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}} + +* * * + +© 2015 Lloyd Brookes <75pound@gmail.com> diff --git a/lib/cli-options.js b/lib/cli-options.js index ba1c887..2ae1142 100644 --- a/lib/cli-options.js +++ b/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, diff --git a/lib/local-web-server.js b/lib/local-web-server.js index 2339e0a..3a6b63e 100644 --- a/lib/local-web-server.js +++ b/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: {}, diff --git a/package.json b/package.json index e394031..f309eb9 100644 --- a/package.json +++ b/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>",