This is the documentation for the next version. For the previous release, see the prev branch. To install this prerelease: $ npm i -g local-web-server@next

local-web-server

A simple web-server for productive front-end development. Typical use cases:

• Front-end Development
  • Static or Single Page App development
  • Re-route paths to local or remote resources
  • Bundle with your front-end project
  • Very little configuration, just a few options
  • Outputs a dynamic statistics view to the terminal
  • Configurable log output, compatible with Goaccess, Logstalgia and glTail
• Back-end service mocking
  • Prototype a web service, microservice, REST API etc.
  • Mocks are defined with config (static), or code (dynamic).
  • CORS-friendly, all origins allowed by default.
• Proxy server
  • Map local routes to remote servers. Removes CORS pain when consuming remote services.
• File sharing

Requires node v4.0.0 or higher.

Synopsis

local-web-server is a simple command-line tool. To use it, from your project directory run ws.

$ ws --help

local-web-server

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

Synopsis

  $ ws [<server options>]
  $ ws --config
  $ ws --help

Server

  -p, --port number              Web server port.
  -d, --directory path           Root directory, defaults to the current directory.
  -f, --log-format string        If a format is supplied an access log is written to stdout. If
                                 not, a dynamic statistics view is displayed. Use a preset ('none',
                                 'dev','combined', 'short', 'tiny' or 'logstalgia') or supply a
                                 custom format (e.g. ':method -> :url').
  -r, --rewrite expression ...   A list of URL rewrite rules. For each rule, separate the 'from'
                                 and 'to' routes with '->'. Whitespace surrounded the routes is
                                 ignored. E.g. '/from -> /to'.
  -s, --spa file                 Path to a Single Page App, e.g. app.html.
  -c, --compress                 Serve gzip-compressed resources, where applicable.
  -b, --forbid path ...          A list of forbidden routes.
  -n, --no-cache                 Disable etag-based caching -forces loading from disk each request.
  --verbose                      Verbose output, useful for debugging.

Misc

  -h, --help    Print these usage instructions.
  --config      Print the stored config.

  Project home: https://github.com/75lb/local-web-server

Examples

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. To run the example projects linked below, clone the project, move into the example directory specified, run ws.

Static site

Fire up your static site on the default port:

$ ws
serving at http://localhost:8000

Example.

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 paths (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.

Example.

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'

Example.

Mock Responses

Mocks give you full control over the response headers and body returned to the client. They can be used to return anything from a simple html string to a resourceful REST API. Typically, they're used to mock services but can be used for anything.

In the config, define an array called mocks. Each mock definition maps a route to a response. A simple home page:

{
  "mocks": [
    {
      "route": "/",
      "response": {
        "body": "<h1>Welcome to the Mock Responses example</h1>"
      }
    }
  ]
}

Under the hood, the property values from the response object are written onto the underlying koa response object. You can set any valid koa response properies, for example type:

{
  "mocks": [
    {
      "route": "/",
      "response": {
        "type": "text/plain",
        "body": "<h1>Welcome to the Mock Responses example</h1>"
      }
    }
  ]
}

To define a conditional response, set a request object on the mock definition. The request value acts as a query - the response defined will only be returned if each property of the request query matches. For example, return an XML response only if the request headers include accept: application/xml, else return 404 Not Found.

{
  "mocks": [
    {
      "route": "/two",
      "request": { "accepts": "xml" },
      "response": {
        "body": "<result id='2' name='whatever' />"
      }
    }
  ]
}

To specify multiple potential responses, set an array of mock definitions to the responses property. The first response with a matching request query will be sent. In this example, the client will get one of two responses depending on the request method:

{
  "mocks": [
    {
      "route": "/three",
      "responses": [
        {
          "request": { "method": "GET" },
          "response": {
            "body": "<h1>Mock response for 'GET' request on /three</h1>"
          }
        },
        {
          "request": { "method": "POST" },
          "response": {
            "status": 400,
            "body": { "message": "That method is not allowed." }
          }
        }
      ]
    }
  ]
}

The examples above all returned static data. To define a dynamic response, create a mock module. Specify its path in the module property:

{
  "mocks": [
    {
      "route": "/four",
      "module": "/mocks/stream-self.js"
    }
  ]
}

Here's what the stream-self module looks like. The module should export a mock definition (an object, or array of objects, each with a response and optional request). In this example, the module simply streams itself to the response but you could set body to any valid value.

const fs = require('fs')

module.exports = {
  response: {
    body: fs.createReadStream(__filename)
  }
}

For more power, define the response as a function. It will receive the koa context as its first argument. Now you have full programmatic control over the response returned.

module.exports = {
  response: function (ctx) {
    ctx.body = '<h1>I can do anything i want.</h1>'
  }
}

If the route contains tokens, their values are passed to the response. For example, with this mock...

{
  "mocks": [
    {
      "route": "/players/:id",
      "module": "/mocks/players.js"
    }
  ]
}

...the id value is passed to the response function. For example, a path of /players/10?name=Lionel would pass 10 to the response function. Additional, the value Lionel would be available on ctx.query.name:

module.exports = {
  response: function (ctx, id) {
    ctx.body = `<h1>id: ${id}, name: ${ctx.query.name}</h1>`
  }
}

Here's an example of a REST collection (users). The config:

{
  "mocks": [
    {
      "route": "/users",
      "module": "/mocks/users.js"
    }
  ]
}

Example.

Stored config

Use the same options every time? Persist then 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. Options set on the command line 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.

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

Example.

Other usage

Debugging

Prints information about loaded middleware, arguments, remote proxy fetches etc.

$ ws --verbose

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

Example.

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]) ⇒ KoaApplication ⏏
    • ~rewriteRule

localWebServer([options]) ⇒ KoaApplication ⏏

Returns a Koa application you can launch or mix into an existing app.

Kind: Exported function
Params

• [options] object - options
  • [.static] object - koa-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, each route being an express route-path.
  • [.spa] string - specify an SPA file to catch requests for everything but static assets.
  • [.log] object - morgan config
    • [.format] string - log format
    • [.options] object - options
  • [.compress] boolean - Serve gzip-compressed resources, where applicable
  • [.mime] object - A list of mime-type overrides, passed directly to mime.define()
  • [.rewrite] Array.<rewriteRule> - One or more rewrite rules
  • [.verbose] boolean - Print detailed output, useful for debugging

Example

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

localWebServer~rewriteRule

The from and to routes are specified using express route-paths

Kind: inner typedef of localWebServer
Properties

Name	Type	Description
from	string	request route
to	string	target route

Example

{
  "rewrite": [
    { "from": "/css/*", "to": "/build/styles/$1" },
    { "from": "/npm/*", "to": "http://registry.npmjs.org/$1" },
    { "from": "/:user/repos/:name", "to": "https://api.github.com/repos/:user/:name" }
  ]
}

---

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