Requires node v4.0.0 or higher. Install the previous release for older node support.

local-web-server

An application shell for building a simple, command-line web server for productive web development.

It is trivial is bundle and deploy with your project. Also deploys to heroku well for demo projects.

It comes with some middleware built-in, which you need not use but will get you up and running for the following use cases:

• Static or Single Page Application front-end development where you have
  • No backend, an existing remote API or need to mock-up an API.

Application Shell

• HTTP or HTTPS server
  • HTTPS is strictly required by some modern techs (ServiceWorker, Media Capture and Streams etc.)
• Add your middleware
  • Use any combination of built-in and custom middleware
  • specify options (for command line or config)
  • Accepts Koa v1 or 2 middleware
• Bundle with your front-end project
• Configuration is via json file or command-line (latter taking presedence)
• Outputs a dynamic statistics view to the terminal

Built-in Middleware (all optional)

• Rewrite routes to local or remote resources
• Efficient, predictable, entity-tag-powered conditional request handling (no need to 'Disable Cache' in DevTools, slowing page-load down)
• Configurable log output, compatible with Goaccess, Logstalgia and glTail
• Proxy server
  • Map local routes to remote servers. Removes CORS pain when consuming remote services.
• 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.

Synopsis

local-web-server is a command-line tool. To serve the current 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.
  --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.
  --https                        Enable HTTPS using a built-in key and cert, registered to the
                                 domain 127.0.0.1.
  --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

Example.

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

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

• local-web-server
  • LocalWebServer ⇐ middleware-stack ⏏
    • instance
      • .add(middleware) ↩︎
    • inner
      • ~collectUserOptions()

LocalWebServer ⇐ middleware-stack ⏏

Kind: Exported class
Extends: middleware-stack

localWebServer.add(middleware) ↩︎

Kind: instance method of LocalWebServer
Chainable
Params

• middleware middleware

LocalWebServer~collectUserOptions()

Return default, stored and command-line options combined

Kind: inner method of LocalWebServer

---

© 2013-16 Lloyd Brookes 75pound@gmail.com. Documented by jsdoc-to-markdown.