Using middleware

Each incoming request passes through your server's middleware stack. You may specify your own personal stack (via --stack) or work with the built-in default.

Built-in Middleware

Name	Description
↓ Body Parser	Parses the request body, making ctx.request.body available to downstream middleware.
↓ Request Monitor	Feeds traffic information to the --verbose output.
↓ Log	Outputs an access log or stats view to the console.
↓ Cors	Support for adding Cross-Origin Resource Sharing (CORS) headers
↓ Json	Pretty-prints JSON responses.
↓ Rewrite	URL Rewriting. Use to re-route requests to local or remote destinations.
↓ Blacklist	Forbid access to sensitive or private resources
↓ Conditional Get	Support for HTTP Conditional requests.
↓ Mime	Customise the mime-type returned with any static resource.
↓ Compress	Compress responses using gzip.
↓ Mock Response	Mock a response for any given request.
↓ SPA	Support for Single Page Applications.
↓ Static	Serves static files.
↓ Index	Serves directory listings.

Local-web-server uses Koa for its middleware stack. See here for a guide explaining how Koa middleware works and why stack order is significant. See here for the ctx object documentation.

Using a personalised stack

A personalised stack can be created by passing middleware module names to --stack. If all you need is to serve static files, the following command is all you need.

$ ws --stack lws-static
Serving at http://mbp.local:8000, http://127.0.0.1:8000, http://192.168.0.100:8000

The lws- prefix in the module name is optional, the following command works the same.

$ ws --stack static
Serving at http://mbp.local:8000, http://127.0.0.1:8000, http://192.168.0.100:8000

You may browse any file in the current folder, e.g. http://127.0.0.1:8000/README.md.

Middleware order

Middleware order is significant. An incoming request is processed by each middleware in turn, in the order they were supplied to --stack. Therefore, if you are using a middleware which processes the body of a request then it must be placed downstream of the middleware which parses the body of a request (typically lws-body-parser). If you are experiencing unexpected issues with your stack, double-check middleware is supplied in the correct order.

Middleware options

Each middleware module may define command-line options. For example, the lws-static module defines several command-line options - you can view them with this command:

$ ws --stack lws-static --help`

Within the output you will find details of the options:

Using config

Your preferred stack can be written to the config file like this.

module.exports = {
  stack: [ 'spa', 'static', 'index' ]
}

View built-in middleware list

If you need reminding of the built-in middleware modules names (in order to pass one or more of them to --stack), you can print them with this command.

$ ws middleware-list
[ 'lws-body-parser',
  'lws-request-monitor',
  'lws-log',
  'lws-cors',
  'lws-json',
  'lws-rewrite',
  'lws-blacklist',
  'lws-conditional-get',
  'lws-mime',
  'lws-compress',
  'lws-mock-response',
  'lws-spa',
  'lws-static',
  'lws-index' ]