|
|
[](https://www.npmjs.org/package/local-web-server)[](https://www.npmjs.org/package/local-web-server)[](https://travis-ci.org/lwsjs/local-web-server)[](https://coveralls.io/github/lwsjs/local-web-server?branch=next)[](https://david-dm.org/lwsjs/local-web-server/next)[](https://github.com/feross/standard)[](https://gitter.im/lwsjs/local-web-server?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
**This documentation is a work in progress**
# local-web-server
The modular web server for productive full-stack development, powered by [lws](https://github.com/lwsjs/lws).
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.* Build your own, personalised CLI web server tool
Features:
* Modular, extensible and easy to personalise. Create, share and consume only 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](https://github.com/lwsjs/local-web-server/wiki/CLI-usage)).
### 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.
```sh$ wsServing 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 (an app with client-side routing, e.g. a React or Angular app) is as trivial as specifying the name of your single page:
```sh$ ws --spa index.htmlServing 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`) return `404 Not Found` as a file at that location 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/`:
```sh$ 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. Mocks are defined in a module which can be reused between projects.
Trivial example - respond to a request for `/rivers` with some JSON. Save the following Javascript in a file named `example-mocks.js`.
```jsmodule.exports = MockBase => class MockRivers extends MockBase { mocks () { return { route: '/rivers', responses: [ { response: { type: 'json', body: [ { name: 'Volga', drainsInto: 'Caspian Sea' }, { name: 'Danube', drainsInto: 'Black Sea' }, { name: 'Ural', drainsInto: 'Caspian Sea' }, { name: 'Dnieper', drainsInto: 'Black Sea' } ] } } ] } }}```
Launch `ws` passing in your mocks module.
```sh$ ws --mocks example-mocks.jsServing at http://mbp.local:8000, http://127.0.0.1:8000, http://192.168.0.100:8000```
GET your rivers.
```sh$ curl http://127.0.0.1:8000/rivers[ { "name": "Volga", "drainsInto": "Caspian Sea" }, { "name": "Danube", "drainsInto": "Black Sea" }, { "name": "Ural", "drainsInto": "Caspian Sea" }, { "name": "Dnieper", "drainsInto": "Black Sea" }]```
More detail can be added to mocks. This example, a RESTful `/users` API, adds responses handling `PUT`, `DELETE` and `POST`.
```jsconst 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: '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}`) } } ] } ] }}```
Launch `ws` passing in your mocks module:
```sh$ ws --mocks example-mocks.jsServing 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 an empty body and the `Location` of the new resource.
```sh$ curl http://127.0.0.1:8000/users -H 'Content-type: application/json' -d '{ "name": "Anthony" }' -iHTTP/1.1 201 CreatedVary: OriginLocation: /users/4Content-Type: text/plain; charset=utf-8Content-Length: 7Date: Wed, 28 Jun 2017 20:31:19 GMTConnection: keep-alive
Created```
A `GET` to `/users` should return our mock user data, including the record just added.
```sh$ 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](https://github.com/lwsjs/local-web-server/wiki) for further configuration options and a guide on how to get the "green padlock" in your browser.
```sh$ ws --httpsServing 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](https://github.com/lwsjs/local-web-server/wiki).
## Install
Requires node v7.6 or higher. Install the [previous release](https://github.com/lwsjs/local-web-server/tree/v1.x) for node >= v4.0.0.
```sh$ npm install -g local-web-server@next```* * *
© 2013-17 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).
|
