Lightweight static web server, zero configuration. Perfect for front-end devs.


Fires up a simple, CORS-enabled, static web server on a given port. Use for local web development or file sharing (directory browsing enabled).

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

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

Then add an start script to your package.json (the standard npm approach):

  "name": "my-web-app",
  "version": "1.0.0",
  "scripts": {
    "start": "ws"

This simplifies a rather specific-looking instruction set like:

$ npm install
$ npm install -g local-web-server
$ ws

to the following, server implementation and launch details abstracted away:

$ npm install
$ npm start
$ ws <server options>
$ ws --config
$ ws --help
-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               Enables compression
-r, --refresh-rate <number>  Statistics view refresh rate in ms. Defaults to 500.
-h, --help                   Print these usage instructions
--config                     Print the stored config

From the folder you wish to serve, run:

$ ws
serving at http://localhost:8000

If you wish to serve a different directory, run:

$ ws -d ~/mysite/
serving /Users/Lloyd/mysite at http://localhost:8000

If you wish to override the default port (8000), use --port or -p:

$ ws --port 9000
serving at http://localhost:9000

To add compression, reducing bandwidth, increasing page load time (by 10-15% on my Macbook Air)

$ ws --compress

Passing a value to --log-format will write an access log to stdout.

Either use a built-in morgan logger preset:

$ ws --log-format short

Or a custom morgan log format:

$ ws -f ':method -> :url'

Or silence:

$ ws -f none

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",
    "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

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

local-web-server is compatible with logstalgia.

On MacOSX, install with homebrew:

$ brew install logstalgia

Alternatively, download a release for your system from github.

Then pipe the logstalgia output format directly into logstalgia for real-time visualisation:

$ ws -f logstalgia | logstalgia -

To use with glTail, write your log to disk using the "default" format:

$ ws -f default > web.log

Then specify this file in your glTail config:

        host: localhost
        source: local
        files: /Users/Lloyd/Documents/MySite/web.log
        parser: apache
        color: 0.2, 0.2, 1.0, 1.0

© 2015 Lloyd Brookes 75pound@gmail.com