[![view on npm](http://img.shields.io/npm/v/local-web-server.svg)](https://www.npmjs.org/package/local-web-server)
[![npm module downloads](http://img.shields.io/npm/dt/local-web-server.svg)](https://www.npmjs.org/package/local-web-server)
[![Build Status](https://travis-ci.org/75lb/local-web-server.svg?branch=master)](https://travis-ci.org/75lb/local-web-server)
[![Dependency Status](https://david-dm.org/75lb/local-web-server.svg)](https://david-dm.org/75lb/local-web-server)
[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/feross/standard)
# 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:
```sh
.
├── css
│ └── style.css
├── index.html
└── package.json
```
### Static site
Fire up your static site on the default port:
```sh
$ 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.
```sh
$ ws --spa index.html
```
By default, typical SPA urls (e.g. `/user/1`, `/login`) would return `404 Not Found` as there is no file at that location on disk. 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 SPA.*
### Access Control
Access to all files is allowed, beside those in the forbidden list (e.g. config files):
```sh
$ ws --forbid .json .yml
serving at http://localhost:8000
```
### URL rewriting
When urls don't map to your directory structure, rewrite:
```sh
$ ws --rewrite /css=>/build/css
```
### Proxy
Rewrite to remote servers (proxy):
```sh
$ ws --rewrite "/api => http://api.example.com/api" \
"/npm => http://registry.npmjs.com" \
"/user/:project/repo -> https://api.github.com/repos/:project"
```
### Stored config
Always use this port and blacklist? Persist it to the config:
```json
{
"name": "example",
"version": "1.0.0",
"local-web-server": {
"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`:
```sh
$ 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"
```
### Mock Responses
*Coming soon*.
### Other features
Compression, caching, simple statistics view, log, override mime types.
## Tips
### Use with Google DevTools Workspaces
### Log Visualisation
Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/wiki/Log-visualisation).
## Install
Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`.
```sh
$ npm install -g local-web-server
```
This will install the `ws` tool globally. To see the available options, run:
```sh
$ 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
```sh
$ npm install local-web-server --save-dev
```
2\. Add a `start` command to your `package.json`:
```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
```sh
$ npm install
$ npm start
serving at http://localhost:8100
```
## Storing default options
To store per-project options, saving you the hassle of inputting them everytime, store them in the `local-web-server` property of your project's `package.json`:
```json
{
"name": "my-project",
"version": "0.11.8",
"local-web-server":{
"port": 8100
}
}
```
Or in a `.local-web-server.json` file stored in the directory you want to serve (typically the root folder of your site):
```json
{
"port": 8100,
"log-format": "tiny"
}
```
Or store global defaults in a `.local-web-server.json` file in your home directory.
```json
{
"port": 3000,
"refresh-rate": 1000
}
```
All stored defaults are overriden by options supplied at the command line.
To view your stored defaults, run:
```sh
$ ws --config
```
## 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()](https://github.com/broofa/node-mime#mimedefine). Example:
```json
{
"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**
```js
const localWebServer = require('local-web-server')
localWebServer().listen(8000)
```
## Composition
* * *
© 2015 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).