local-web-server

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

Requires node v4.0.0 or higher.

Synopsis

For the examples below, assume we're in a project 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 as there is no file at that location on disk. By marking index.html as the SPA you create this rule:

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 SPA.

Access Control

Access to all files is allowed, beside those in the forbidden list (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

Proxy

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"

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$"
  }
}

Logging

By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use --log-format:

$ ws --log-format combined
serving at http://localhost:8000
::1 - - [16/Nov/2015:11:16:52 +0000] "GET / HTTP/1.1" 200 12290 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2562.0 Safari/537.36"

Mock Responses

Coming soon.

Other features

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

Tips

Use with Google DevTools Workspaces

Log Visualisation

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

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

This will install the ws tool globally. To see the available options, run:

$ ws --help

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
serving at http://localhost:8100

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" ]
    }
}

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')
localWebServer().listen(8000)

Composition

---

© 2015 Lloyd Brookes 75pound@gmail.com. Documented by jsdoc-to-markdown.