local-web-server

The modular web server for productive full-stack development.

Use this tool to:

Build any flavour of web application (static site, dynamic site with client or server-rendered content, Single Page App, Progessive Web App, Angular or React app etc.)
Prototype any CORS-enabled back-end service (e.g. RESTful HTTP API or Microservice using websockets, Server Sent Events etc.)
Monitor activity, analyse performance, experiment with caching strategies etc.

Features:

Modular, extensible and easy to personalise. Create, share and consume the plugins which match your requirements.
Powerful, extensible command-line interface (add your own commands and options)
HTTP, HTTPS and experimental HTTP2 support
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).

Static web site

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 a directory listing or your index.html, if that file exists.

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

Single Page Application

Serving a Single Page Application (e.g. a React or Angular app) is as trivial as specifying the name of your single page:

$ ws --spa index.html
Serving at http://mbp.local:8000, http://127.0.0.1:8000, http://192.168.0.100:8000

By default, requests for typical SPA paths (e.g. /user/1, /login) would return 404 Not Found as a file at that locaiton does not exist. 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.

URL rewriting and proxied requests

Another common use case is to re-route 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

Mock responses

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

module.exports = MockBase => class MockUsers extends MockBase {
  mocks () {
    /* response mocks for /users */
    return [
      {
        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)
              newUser.id = users.length
              ctx.status = 201
              ctx.response.set('Location', `/users/${newUser.id}`)
            }
          }
        ]
      }
    ]
  }
}

Next, launch ws passing in your mocks module:

$ 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
  },
  {
    "id": 2,
    "name": "Mona",
    "age": 34
  },
  {
    "id": 3,
    "name": "Francesco",
    "age": 24
  },
  {
    "id": 4,
    "name": "Anthony"
  }

HTTPS

Launching a secure server is as simple as setting the --https flag. See the wiki for further configuration options and a guide on how to get the "green padlock" in your browser.

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

Further Documentation

See the wiki for plenty more 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

6.7 KiB Raw Blame History