16 KiB
This is the documentation for the next version. For the previous release, see the prev
branch. To install this prerelease: $ npm i -g local-web-server@next
local-web-server
A simple web-server for productive front-end development. Typical use cases:
- Front-end Development
- Static or Single Page App development
- Re-route paths to local or remote resources
- Bundle with your front-end project
- Very little configuration, just a few options
- Outputs a dynamic statistics view to the terminal
- Configurable log output, compatible with Goaccess, Logstalgia and glTail
- Back-end service mocking
- Prototype a web service, microservice, REST API etc.
- Mocks are defined with config (static), or code (dynamic).
- CORS-friendly, all origins allowed by default.
- Proxy server
- Map local routes to remote servers. Removes CORS pain when consuming remote services.
- File sharing
Requires node v4.0.0 or higher.
Synopsis
local-web-server is a simple command-line tool. To use it, from your project directory run ws
.
$ 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.
--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
Examples
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 ws
.
Static site
Fire up your static site on the default port:
$ ws
serving at http://localhost:8000
Single Page Application
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. /user/1
, /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.
URL rewriting
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 /css
):
$ 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 /css
path:
$ ws --rewrite '/css/* -> /build/css/$1'
this rewrites /css/a
as /build/css/a
, /css/a/b/c
as /build/css/a/b/c
etc.
Proxied requests
If the 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/* -> http://registry.npmjs.org/$1'
Map local requests for repo data to the Github API:
$ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name'
Mock Responses
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:
{
"mocks": [
{
"route": "/",
"response": {
"body": "<h1>Welcome to the Mock Responses example</h1>"
}
}
]
}
Under the hood, the property values from the response
object are written onto the underlying koa response object. You can set any valid koa response properies, for example type:
{
"mocks": [
{
"route": "/",
"response": {
"type": "text/plain",
"body": "<h1>Welcome to the Mock Responses example</h1>"
}
}
]
}
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.
{
"mocks": [
{
"route": "/two",
"request": { "accepts": "xml" },
"response": {
"body": "<result id='2' name='whatever' />"
}
}
]
}
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:
{
"mocks": [
{
"route": "/three",
"responses": [
{
"request": { "method": "GET" },
"response": {
"body": "<h1>Mock response for 'GET' request on /three</h1>"
}
},
{
"request": { "method": "POST" },
"response": {
"status": 400,
"body": { "message": "That method is not allowed." }
}
}
]
}
]
}
The examples above all returned static data. To define a dynamic response, create a mock module. Specify its path in the module
property:
{
"mocks": [
{
"route": "/four",
"module": "/mocks/stream-self.js"
}
]
}
Here's what the stream-self
module looks like. The module should export a mock definition (an object with a response
and optional request
). In this example, the module simply streams itself to the response but you could craft and return any valid value.
const fs = require('fs')
module.exports = {
response: {
body: fs.createReadStream(__filename)
}
}
For more power, define the response body as a function. It will receive the koa context as its first argument. Now you have full programmatic control over the response returned.
const fs = require('fs')
module.exports = {
response: {
body: function (ctx) {
ctx.body = '<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...
{
"mocks": [
{
"route": "/five/:id",
"module": "/mocks/example.js"
}
]
}
...the id
value is passed to the body function. For example, a path of /five/10?name=Lionel
would pass 10
to the body function. Additional, the value Lionel
would be available on ctx.query.name
:
const fs = require('fs')
module.exports = {
response: {
body: function (ctx, id) {
ctx.body = `<h1>id: ${id}, name: ${ctx.query.name}</h1>`
}
}
}
Here's an example of a REST collection (users). The config:
{
"mocks": [
{
"route": "/users",
"module": "/mocks/users.js"
}
]
}
Stored config
Use the same port and blacklist every time? Persist it to package.json
:
{
"name": "example",
"version": "1.0.0",
"local-web-server": {
"port": 8100,
"forbid": "*.json"
}
}
or .local-web-server.json
{
"port": 8100,
"forbid": "*.json"
}
local-web-server will merge and use all config found, searching from the current directory upward. In the case both package.json
and .local-web-server.json
config is found in the same directory, .local-web-server.json
will take precedence. Command-line options take precedence over all.
To inspect stored config, run:
$ ws --config
Logging
By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use --log-format
:
$ ws --log-format combined
serving 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.
Access Control
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
Other usage
Debugging
Prints information about loaded middleware, arguments, remote proxy fetches etc.
$ ws --verbose
Compression
Serve gzip-compressed resources, where applicable
$ ws --compress
Disable caching
Disable etag response headers, forcing resources to be served in full every time.
$ ws --no-cache
mime-types
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:
{
"mime": {
"text/plain": [ "php", "pl" ]
}
}
Log Visualisation
Instructions for how to visualise log output using goaccess, logstalgia or gltail here.
Install
Ensure node.js is installed first. Linux/Mac users may need to run the following commands with sudo
.
$ npm install -g local-web-server
This will install the ws
tool globally. To see the available options, run:
$ ws --help
Distribute with your project
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 package.json
:
{
"name": "example",
"version": "1.0.0",
"local-web-server": {
"port": 8100,
"forbid": "*.json"
},
"scripts": {
"start": "ws"
}
}
3. Document how to build and launch your site
$ npm install
$ npm start
serving at http://localhost:8100
API Reference
localWebServer([options]) ⇒ KoaApplication
⏏
Returns a Koa application you can launch or mix into an existing app.
Kind: Exported function
Params
- [options]
object
- options- [.static]
object
- koa-static config- [.root]
string
= "."
- root directory - [.options]
string
- options
- [.root]
- [.serveIndex]
object
- koa-serve-index config- [.path]
string
= "."
- root directory - [.options]
string
- options
- [.path]
- [.forbid]
Array.<string>
- A list of forbidden routes, each route being an express route-path. - [.spa]
string
- specify an SPA file to catch requests for everything but static assets. - [.log]
object
- morgan config- [.format]
string
- log format - [.options]
object
- options
- [.format]
- [.compress]
boolean
- Serve gzip-compressed resources, where applicable - [.mime]
object
- A list of mime-type overrides, passed directly to mime.define() - [.rewrite]
Array.<rewriteRule>
- One or more rewrite rules - [.verbose]
boolean
- Print detailed output, useful for debugging
- [.static]
Example
const localWebServer = require('local-web-server')
localWebServer().listen(8000)
localWebServer~rewriteRule
The from
and to
routes are specified using express route-paths
Kind: inner typedef of localWebServer
Properties
Name | Type | Description |
---|---|---|
from | string |
request route |
to | string |
target route |
Example
{
"rewrite": [
{ "from": "/css/*", "to": "/build/styles/$1" },
{ "from": "/npm/*", "to": "http://registry.npmjs.org/$1" },
{ "from": "/:user/repos/:name", "to": "https://api.github.com/repos/:user/:name" }
]
}
© 2015 Lloyd Brookes 75pound@gmail.com. Documented by jsdoc-to-markdown.