This documentation is a work in progress

local-web-server

The modular web server for productive full-stack development.

Use this tool to:

• Build fast, modern web applications using any tech, framework or architecture.
• Prototype back-end services (RESTful HTTP API, Microservice, websocket server etc.)
• Monitor activity, analyse performance, compare caching strategies etc.

Features:

• HTTP, HTTPS and HTTP2 support
• Modular. Create, share and consume middleware, view and server plugins.
• URL Rewriting to local or remote destinations
• Single Page Application support
• Response mocking
• Configurable access log
• Route blacklisting
• HTTP Conditional Request support
• Gzip response compression and much more

Synopsis

This package installs the ws command-line tool (take a look at the usage guide). The most simple use case is to run ws without any arguments - this will host the current directory as a static web site. Navigating to the server will render your index.html or show a directory listing, if you don't have one.

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

Another common use case is to proxy certain requests to a remote server if, for example, you'd like to use data from a different environment. The following command would proxy requests with a URL beginning with http://127.0.0.1:8000/api/ to https://internal-service.local/api/:

$ ws --rewrite '/api/* -> https://internal-service.local/api/$1`
Serving at http://mbp.local:8000, http://127.0.0.1:8000, http://192.168.0.100:8000

Imagine the network is down or you're working offline, proxied requests to https://internal-service.local/api/users/1 would fail. In this case, Mock Responses can fill the gap. Export your mock responses from a module.

const users = [
  { "id": 1, "name": "Lloyd", "age": 40 },
  { "id": 2, "name": "Mona", "age": 34 },
  { "id": 3, "name": "Francesco", "age": 24 }
]

/* response mocks for /users */
module.exports = [
  {
    route: '/users',
    responses: [
      /* Respond with 400 Bad Request for PUT and DELETE requests (inappropriate on a collection) */
      { request: { method: 'PUT' }, response: { status: 400 } },
      { request: { method: 'DELETE' }, response: { status: 400 } },
      {
        /* for GET requests return the collection */
        request: { method: 'GET' },
        response: { type: 'application/json', body: users }
      },
      {
        /* for POST requests, create a new user and return its location */
        request: { method: 'POST' },
        response: function (ctx) {
          const newUser = ctx.request.body
          users.push(newUser)
          ctx.status = 201
          ctx.response.set('Location', `/users/${users.length}`)
        }
      }
    ]
  }
]

Next, launch ws passing in your mock response file:

$ ws --mocks example-mocks.js
Serving at http://mbp.local:8000, http://127.0.0.1:8000, http://192.168.0.100:8000

Test your mock responses. A POST request should return a 201 with a Location header and empty body.

$ curl http://127.0.0.1:8000/users -H 'Content-type: application/json' -d '{ "name": "Anthony" }' -i
HTTP/1.1 201 Created
Vary: Origin
Location: /users/4
Content-Type: text/plain; charset=utf-8
Content-Length: 7
Date: Wed, 28 Jun 2017 20:31:19 GMT
Connection: keep-alive

A GET to /users should return our mock user data, including the record just added.

$ curl http://127.0.0.1:8000/users
[
  {
    "id": 1,
    "name": "Lloyd",
    "age": 40,
    "nationality": "English"
  },
  {
    "id": 2,
    "name": "Mona",
    "age": 34,
    "nationality": "Palestinian"
  },
  {
    "id": 3,
    "name": "Francesco",
    "age": 24,
    "nationality": "Italian"
  },
  {
    "id": 4,
    "name": "Anthony"
  }

Advanced Usage

Being modular and extensible, features can be added or removed from ws in the shape of Middleware, ServerFactory or View modules. See the wiki for full documentation and tutorials.

Install

Requires node v7.6 or higher. Install the previous release for node >= v4.0.0.

$ npm install -g local-web-server@next

---

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