5.6 KiB
local-web-server
A simple web-server for productive front-end development.
Requires node v4.0.0 or higher.
Synopsis
For the examples below, assume we're in a project directory looking like this:
.
├── css
│ └── style.css
├── index.html
└── package.json
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 urls (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.
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
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 '/projects/:user/repos/:name -> https://api.github.com/repos/:user/:name'
Stored config
Always use this port and blacklist? 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"
}
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"
Other features
Serve gzip-compressed resources, where applicable
$ ws --compress
Disable etag-based caching
$ ws --no-cache
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
mime-types
You can set additional mime-type/extension mappings, or override the defaults by setting a mime
value in your local config. This value is passed directly to mime.define(). Example:
{
"mime": {
"text/plain": [ "php", "pl" ]
}
}
API Reference
local-web-server
localWebServer([options]) ⏏
Returns a Koa application
Kind: Exported function
Param | Type | Description |
---|---|---|
[options] | object |
options |
[options.forbid] | Array.<regexp> |
a list of forbidden routes. |
Example
const localWebServer = require('local-web-server')
localWebServer().listen(8000)
© 2015 Lloyd Brookes 75pound@gmail.com. Documented by jsdoc-to-markdown.