local-web-server

A simple web-server for productive front-end development.

Requires node v4.0.0 or higher.

Synopsis

Some typical use cases. For these examples, assume we're in a site directory looking like this:

.
├── css
│   └── style.css
├── index.html
└── package.json

Static site

Fire up your static site on the default port:

$ ws
serving at http://localhost:8000

Single Page Application

You're building a web app with client-side routing, so mark index.html as the SPA.

$ ws --spa index.html

By default, typical SPA urls (e.g. /user/1, /login) would return 404 Not Found. By marking index.html as the SPA you create this rule: if a file with that url exists (e.g. /css/style.css) then serve it, if it does not (e.g. /login) then pass it to the SPA.

Access Control

Access to all files is allowed, beside those you forbid (e.g. config files):

$ ws --forbid .json .yml
serving at http://localhost:8000

URL rewriting

When urls don't map to your directory structure, rewrite:

$ ws --rewrite /css=>/build/css

Rewrite to remote servers (proxy):

$ ws --rewrite "/api => http://api.example.com/api" \
               "/npm => http://registry.npmjs.com" \
               "/user/:project/repo -> https://api.github.com/repos/:project"

Mock Responses

Stored config

Always use this port and blacklist? Persist it to the config:

{
  "name": "example",
  "version": "1.0.0",
  "local-web-server": {
    "port": 8100,
    "forbid": "\\.json$"
  }
}

Other features

Compression, caching, simple statistics view, log, override mime types.

Install

Ensure node.js is installed first. Linux/Mac users may need to run the following commands with sudo.

$ npm install -g local-web-server

Distribute with your project

The standard convention with client-server applications is to add an npm start command to launch the server component.

1. Install the server as a dev dependency

$ npm install local-web-server --save-dev

2. Add a start command to your package.json:

{
  "name": "example",
  "version": "1.0.0",
  "local-web-server": {
    "port": 8100,
    "forbid": "\\.json$"
  },
  "scripts": {
    "start": "ws"
  }
}

3. Document how to build and launch your site

$ npm install
$ npm start

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:

{
  "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):

{
  "port": 8100,
  "log-format": "tiny"
}

Or store global defaults in a .local-web-server.json file in your home directory.

{
  "port": 3000,
  "refresh-rate": 1000
}

All stored defaults are overriden by options supplied at the command line.

To view your stored defaults, run:

$ 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(). Example:

{
    "mime": {
        "text/plain": [ "php", "pl" ]
    }
}

Use with Google DevTools Workspaces

Log Visualisation

Instructions for how to visualise log output using goaccess, logstalgia or gltail here.

API Reference

local-web-server

localWebServer([options]) ⏏

Returns a Koa application

Kind: Exported function

Param	Type	Description
[options]	object	options
[options.forbid]	Array.<regexp>	a list of forbidden routes.

Example

const localWebServer = require('local-web-server')

---

© 2015 Lloyd Brookes 75pound@gmail.com