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 a file does not exist with that path. 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 and handle the route client-side.

Access Control

By default, access to all files is allowed (including dot files). Use --forbid to establish a blacklist:

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

Path syntax

URL rewriting

Your application requested /css/style.css but it's stored at /build/css/style.css. Create a rewrite rule:

$ ws --rewrite "/css/style.css -> /build/css/style.css"

Or, more generally (matching any stylesheet path under /css):

$ ws --rewrite "/css/:stylesheet -> /build/css/:stylesheet"

If a deep structure is involved it may be easier to mount the entire contents of /build/css to the /css path: (matches any stylesheet path under /css, /css/a, /css/a/b etc.)

$ ws --rewrite "/css/* -> /build/css/$1"

Proxied rewrite

If the to address contains a hostname local-web-server will act as a proxy - the remote resource will be fetched and returned

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