diff --git a/README.md b/README.md index 3581f29..04b9800 100644 --- a/README.md +++ b/README.md @@ -5,96 +5,102 @@ [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/feross/standard) [![Join the chat at https://gitter.im/lwsjs/local-web-server](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/lwsjs/local-web-server?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -***Requires node v7.6 or higher. Install the [previous release](https://github.com/lwsjs/local-web-server/tree/prev) for older node support.*** +***Requires node v7.6 or higher. Install the [previous release](https://github.com/lwsjs/local-web-server/tree/v1.x) for older node support. Documentation still WIP.*** # local-web-server -At its core, local-web-server is an application shell for building a specialised command-line web server to support productive Web Platform engineers. When combined with built-in and custom features it's in intended to by a powerful tool in helping build and debug Web applications. It comes bundled with a middleware stack covering common requirements but any arbitrary stack can be specified from the command line or config. -Being an npm module, it is trivial is bundle and distribute/deploy with your web application. +A convenient local web server to support productive, full-stack Javascript development. Built on [lws](https://github.com/lwsjs/lws). -**Typically used for building:** +**Features** -* Simple static site -* Single Page Application - * Works well with React, Angular or vanilla JS. +- Lightweight +- http/https ([http2](https://github.com/nodejs/http2) will be added once ready) +- Rewrite routes to local or remote resources + - Url rewriting + - Proxy certain routes to a remote server (e.g. an existing API). Avoids CORS pain when consuming remote services. +- Configurable by command-line options, stored config or both +- 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](https://github.com/lwsjs/local-web-server/blob/master/doc/visualisation.md) +- Configurable CORS rules. All origins allowed by default. -**Backend scenarios covered:** +**Use cases** -* Existing API -* Mock API -* Websocket server - -**Server options** - -* HTTP or HTTPS server - * HTTPS is strictly required by some modern techs (ServiceWorker, Media Capture and Streams etc.) -* Configurable middleware stack - * Use any combination of built-in and custom middleware - * specify options (for command line or config) - * Accepts Koa v1 or 2 middleware - -**Built-in Middleware stack** - - * 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](https://github.com/lwsjs/local-web-server/blob/master/doc/visualisation.md) - * 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. - -**Personalised stack** +Things you can build: +- Simple static website +- Single Page Application + - Works well with React, Angular or vanilla JS. +- Real or mock web services + - e.g. a RESTful API or microservice + - Mocks are defined with config (static), or code (dynamic). +- Websocket server ## 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.
+ A convenient local web server to support productive, full-stack Javascript
+ development.
Synopsis
- $ ws [--verbose] [] []
+ $ ws [--verbose] [--config-file file] [] []
$ ws --config
$ ws --help
+ $ ws --version
+
+General
+
+ -h, --help Print these usage instructions.
+ --config Print the active config.
+ -c, --config-file file Config filename to use, defaults to "lws.config.js".
+ -v, --verbose Verbose output.
+ --version Print the version number.
Server
- -p, --port number Web server port.
- --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.
+ -p, --port number Web server port.
+ --hostname string The hostname (or IP address) to listen on. Defaults to 0.0.0.0.
+ --stack feature ... Feature stack.
+ --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.
Middleware
+ -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', 'stats', or 'logstalgia') or supply a custom format (e.g.
+ ':method -> :url').
+ --cors.origin Access-Control-Allow-Origin value. Default is request Origin header.
+ --cors.allow-methods Access-Control-Allow-Methods value. Default is
+ "GET,HEAD,PUT,POST,DELETE,PATCH"
-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'.
-b, --forbid path ... A list of forbidden routes.
- -n, --no-cache Disable etag-based caching -forces loading from disk each request.
- -c, --compress Serve gzip-compressed resources, where applicable.
- -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').
- -s, --spa file Path to a Single Page App, e.g. app.html.
+ -n, --no-cache Disable etag-based caching - forces loading from disk each request.
+ -z, --compress Serve gzip-compressed resources, where applicable.
+ --compress.threshold number Minimum response size in bytes to apply compression. Defaults to 1024 bytes.
+ --spa file Path to a Single Page App, e.g. app.html.
+ --spa.asset-test RegExp A regular expression to identify an asset file. Defaults to "\.".
-d, --directory path Root directory, defaults to the current directory.
-
-Misc
-
- -h, --help Print these usage instructions.
- --config Print the stored config.
+ --static.maxage number Browser cache max-age in milliseconds.
+ --static.defer If true, serves after `yield next`, allowing any downstream middleware to
+ respond first.
+ --static.index path Default file name, defaults to `index.html`.
+ --index.root path Index root directory, defaults to --directory or the current directory.
+ --index.hidden Show hidden files.
+ --index.view name Display mode, either `tiles` or `details`. Defaults to tiles.
Project home: https://github.com/lwsjs/local-web-server
-
## Install
```sh
diff --git a/package.json b/package.json
index 42ed72e..79a793e 100644
--- a/package.json
+++ b/package.json
@@ -42,7 +42,7 @@
"lws-compress": "^0.1.0",
"lws-conditional-get": "^0.1.0",
"lws-cors": "^0.1.0",
- "lws-index": "^0.1.0",
+ "lws-index": "^0.1.1",
"lws-json": "^0.1.0",
"lws-log": "^0.1.1",
"lws-mime": "^0.1.0",
@@ -50,7 +50,7 @@
"lws-rewrite": "^0.1.0",
"lws-spa": "^0.1.0",
"lws-static": "^0.1.1",
- "lws": "^1.0.0-pre.3"
+ "lws": "^1.0.0-pre.4"
},
"devDependencies": {
"test-runner": "^0.3.0"
diff --git a/test/test.js b/test/test.js
index e7054b6..394c7d6 100644
--- a/test/test.js
+++ b/test/test.js
@@ -10,7 +10,7 @@ runner.test('basic', async function () {
const port = 9000 + this.index
const localWebServer = new LocalWebServer({
port: port,
- 'static.root': 'test/fixture',
+ directory: 'test/fixture',
'log.format': 'none'
})
localWebServer.start()