local-web-server

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

Requires node v4.0.0 or higher.

Synopsis

For the examples below, we assume we're in a project directory looking like this:

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

All paths/routes are specified using express syntax.

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

URL rewriting

Your application requested /css/style.css but it's stored at /build/css/style.css. To avoid a 404 you need a rewrite rule:

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

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

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

With a deep CSS directory structure it may be easier to mount the entire contents of /build/css to the /css path:

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

this rewrites /css/a as /build/css/a, /css/a/b/c as /build/css/a/b/c etc.

Proxied requests

If the to URL contains a remote host, local-web-server will act as a proxy - fetching and responding with the remote resource.

Mount the npm registry locally:

$ ws --rewrite '/npm/* -> http://registry.npmjs.org/$1'

Map local requests for repo data to the Github API:

$ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name'

Stored config

Use the same port and blacklist every time? Persist it to package.json:

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

or .local-web-server.json

{
  "port": 8100,
  "forbid": "*.json"
}

local-web-server will merge and use all config found, searching from the current directory upward. In the case both package.json and .local-web-server.json config is found in the same directory, .local-web-server.json will take precedence. Command-line options take precedence over all.

To inspect stored config, run:

$ ws --config

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"

The format value supplied is passed directly to morgan. The exception is --log-format none which disables all output.

Other usage

Compression

Serve gzip-compressed resources, where applicable

$ ws --compress

Disable caching

Disable etag response headers, forcing resources to be served in full every time.

$ ws --no-cache

mime-types

You can set additional mime-type/extension mappings, or override the defaults by setting a mime value in the stored config. This value is passed directly to mime.define(). Example:

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

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

API Reference

local-web-server

localWebServer([options]) ⏏

Returns a Koa application

Kind: Exported function
Params

• [options] object - options
  • [.static] object - koajs/static config
    • [.root] string - root directory
    • [.options] string - options
  • [.serveIndex] object - koa-serve-index config
    • [.path] string - root directory
    • [.options] string - options
  • [.forbid] Array.<string> - a list of forbidden routes.

Example

const localWebServer = require('local-web-server')
localWebServer().listen(8000)

---

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