A simple web-server for productive front-end development
Requires node v4.0.0 or higher. Install the previous release for older node support.
A simple web-server for productive front-end development. Typical use cases:
local-web-server is a simple command-line tool. To use it, from your project directory run
$ 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. --key file SSL key. Supply along with --cert to launch a https server. --cert file SSL cert. Supply along with --key to launch a https server. --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
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
Fire up your static site on the default port:
$ wsserving at http://localhost:8000
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.
/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.
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
$ 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
$ ws --rewrite '/css/* -> /build/css/$1'
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/* -> $1'
Map local requests for repo data to the Github API:
$ ws --rewrite '/:user/repos/:name -> '
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:
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.
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:
The examples above all returned static data. To define a dynamic response, create a mock module. Specify its path in the
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'moduleexports =response:body: fscreateReadStream__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.
moduleexports =ctxbody = '<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...
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
moduleexports =ctxbody = `<h1>id: , name: </h1>`
Here's an example of a REST collection (users). We'll create two routes, one for actions on the resource collection, one for individual resource actions.
Define a module (
users.json) defining seed data:
The collection module:
const users = require'./users.json'/* responses for /users */const mockResponses =/* Respond with 400 Bad Request for PUT and DELETE - inappropriate on a collection */request: method: 'PUT' response: status: 400request: method: 'DELETE' response: status: 400/* for GET requests return a subset of data, optionally filtered on 'minAge' and 'nationality' */request: method: 'GET'ctxbody = usersfilteruser =>const meetsMinAge = userage || 1000 >= NumberctxqueryminAge || 0const requiredNationality = usernationality === ctxquerynationality || usernationalityreturn meetsMinAge && requiredNationality/* for POST requests, create a new user and return the path to the new resource */request: method: 'POST'const newUser = ctxrequestbodyuserspushnewUsernewUserid = userslengthctxstatus = 201ctxresponseset'Location' `/users/`moduleexports = mockResponses
The individual resource module:
const users = require'./users.json'/* responses for /users/:id */const mockResponses =/* don't support POST here */request: method: 'POST' response: status: 400/* for GET requests, return a particular user */request: method: 'GET'ctxbody = usersfinduser => userid === Numberid/* for PUT requests, update the record */request: method: 'PUT'const updatedUser = ctxrequestbodyconst existingUserIndex = usersfindIndexuser => userid === NumberidusersspliceexistingUserIndex 1 updatedUserctxstatus = 200/* DELETE request: remove the record */request: method: 'DELETE'const existingUserIndex = usersfindIndexuser => userid === NumberidusersspliceexistingUserIndex 1ctxstatus = 200moduleexports = mockResponses
Some modern techs (ServiceWorker, any
MediaDevices.getUserMedia() request etc.) must be served from a secure origin (HTTPS). To launch an HTTPS server, supply a
--cert to local-web-server, for example:
$ ws --key localhost.key --cert localhost.crt
If you don't have a key and certificate it's trivial to create them. You do not need third-party verification (Verisign etc.) for development purposes. To get the green padlock in the browser, the certificate..
Common Namevalue matching the FQDN of the server
First create a certificate:
$ brew install openssl
$ openssl genrsa -des3 -passout pass:x -out ws.pass.key 2048
$ openssl rsa -passin pass:x -in ws.pass.key -out ws.key
Common Name, you can accept the default values for the others. Important: you must input your server's correct FQDN (
laptop.homeetc.) into the
Common Namefield. The cert is only valid for the domain specified here. You can find out your computers host name by running the command
hostname. For example, mine is
$ openssl req -new -key ws.key -out ws.csr
$ openssl x509 -req -days 365 -in ws.csr -signkey ws.key -out ws.crt
$ rm ws.pass.key ws.csr
Common Name) to launch your browser.
$ ws --key ws.key --cert ws.crtserving at , ,
Chrome and Firefox will still complain your certificate has not been verified by a Certificate Authority. Firefox will offer you an
Add an exception option, allowing you to ignore the warning and manually mark the certificate as trusted. In Chrome on Mac, you can manually trust the certificate another way:
.crtfile you created.
Certificatescategory, double-click the cert you imported.
when using this certificate, select
Now you have a valid, trusted certificate for development.
Use the same options every time? Persist then to
local-web-server will merge and use all config found, searching from the current directory upward. In the case both
.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
By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use
$ ws --log-format combinedserving 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.
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
Prints information about loaded middleware, arguments, remote proxy fetches etc.
$ ws --verbose
Serve gzip-compressed resources, where applicable
$ ws --compress
Disable etag response headers, forcing resources to be served in full every time.
$ ws --no-cache
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:
Instructions for how to visualise log output using goaccess, logstalgia or gltail here.
Ensure node.js is installed first. Linux/Mac users may need to run the following commands with
$ npm install -g local-web-server
This will install the
ws tool globally. To see the available options, run:
$ ws --help
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
3. Document how to build and launch your site
$ npm install$ npm startserving at http://localhost:8100
Returns a Koa application you can launch or mix into an existing app.
Kind: Exported function
object- koa-static config
= "."- root directory
object- koa-serve-index config
= "."- root directory
Array.<string>- A list of forbidden routes, each route being an express route-path.
string- specify an SPA file to catch requests for everything but static assets.
object- morgan config
boolean- Serve gzip-compressed resources, where applicable
object- A list of mime-type overrides, passed directly to mime.define()
Array.<rewriteRule>- One or more rewrite rules
boolean- Print detailed output, useful for debugging
const localWebServer = require'local-web-server'localWebServerlisten8000
to routes are specified using express route-paths
Kind: inner typedef of