Browse Source

docs

master
Lloyd Brookes 9 years ago
parent
commit
d52dc38a91
  1. 117
      README.md
  2. 95
      bin/cli.js
  3. 148
      jsdoc2md/README.hbs
  4. 2
      lib/cli-options.js
  5. 13
      lib/local-web-server.js
  6. 3
      package.json

117
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) [![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) [![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) [![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**. **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 ## Install
Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`. 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 $ 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 ### Logging
Passing a value to `--log-format` will write an access log to `stdout`. 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 -
```
<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
![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] | <code>object</code> | options |
| [options.blacklist] | <code>Array.&lt;regexp&gt;</code> | 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')
``` ```
* * * * * *

95
bin/cli.js

@ -9,49 +9,45 @@ const cliOptions = require('../lib/cli-options')
const loadConfig = require('config-master') const loadConfig = require('config-master')
const path = require('path') const path = require('path')
const options = {}
/* parse command line args */
const cli = commandLineArgs(cliOptions.definitions) const cli = commandLineArgs(cliOptions.definitions)
const usage = cli.getUsage(cliOptions.usageData) 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({ 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) console.log(usage)
process.exit(1) process.exit(1)
} }
@ -60,8 +56,31 @@ function onServerUp () {
const e = Date.now() const e = Date.now()
const time = `${e-s}ms` const time = `${e-s}ms`
console.error(ansi.format( 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
}

148
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>

2
lib/cli-options.js

@ -18,7 +18,7 @@ module.exports = {
}, },
{ {
name: 'no-cache', alias: 'n', type: Boolean, 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, name: 'help', alias: 'h', type: Boolean,

13
lib/local-web-server.js

@ -21,9 +21,18 @@ const send = require('koa-send')
/** /**
* @module local-web-server * @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({ options = Object.assign({
static: {}, static: {},
serveIndex: {}, serveIndex: {},

3
package.json

@ -22,7 +22,8 @@
"node": ">=4.0.0" "node": ">=4.0.0"
}, },
"scripts": { "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", "repository": "https://github.com/75lb/local-web-server",
"author": "Lloyd Brookes <75pound@gmail.com>", "author": "Lloyd Brookes <75pound@gmail.com>",

Loading…
Cancel
Save