docs
This commit is contained in:
Lloyd Brookes
36
README.md
36
README.md
@ -141,11 +141,6 @@ Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need
|
||||
$ 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.
|
||||
|
||||
@ -179,37 +174,6 @@ $ npm start
|
||||
serving at http://localhost:8100
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
|
||||
* [local-web-server](#module_local-web-server)
|
||||
* [LocalWebServer](#exp_module_local-web-server--LocalWebServer) ⇐ <code>[middleware-stack](#module_middleware-stack)</code> ⏏
|
||||
* _instance_
|
||||
* [.add(middleware)](#) ↩︎
|
||||
* _inner_
|
||||
* [~collectUserOptions()](#module_local-web-server--LocalWebServer..collectUserOptions)
|
||||
|
||||
<a name="exp_module_local-web-server--LocalWebServer"></a>
|
||||
|
||||
### LocalWebServer ⇐ <code>[middleware-stack](#module_middleware-stack)</code> ⏏
|
||||
**Kind**: Exported class
|
||||
**Extends:** <code>[middleware-stack](#module_middleware-stack)</code>
|
||||
<a name=""></a>
|
||||
|
||||
#### localWebServer.add(middleware) ↩︎
|
||||
**Kind**: instance method of <code>[LocalWebServer](#exp_module_local-web-server--LocalWebServer)</code>
|
||||
**Chainable**
|
||||
**Params**
|
||||
|
||||
- middleware <code>[middleware](#module_middleware-stack--MiddlewareStack..middleware)</code>
|
||||
|
||||
<a name="module_local-web-server--LocalWebServer..collectUserOptions"></a>
|
||||
|
||||
#### LocalWebServer~collectUserOptions()
|
||||
Return default, stored and command-line options combined
|
||||
|
||||
**Kind**: inner method of <code>[LocalWebServer](#exp_module_local-web-server--LocalWebServer)</code>
|
||||
|
||||
* * *
|
||||
|
||||
© 2013-16 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).
|
||||
|
||||
30
doc/api.md
Normal file
30
doc/api.md
Normal file
@ -0,0 +1,30 @@
|
||||
## API Reference
|
||||
|
||||
|
||||
* [local-web-server](#module_local-web-server)
|
||||
* [LocalWebServer](#exp_module_local-web-server--LocalWebServer) ⇐ <code>[middleware-stack](#module_middleware-stack)</code> ⏏
|
||||
* _instance_
|
||||
* [.add(middleware)](#) ↩︎
|
||||
* _inner_
|
||||
* [~collectUserOptions()](#module_local-web-server--LocalWebServer..collectUserOptions)
|
||||
|
||||
<a name="exp_module_local-web-server--LocalWebServer"></a>
|
||||
|
||||
### LocalWebServer ⇐ <code>[middleware-stack](#module_middleware-stack)</code> ⏏
|
||||
**Kind**: Exported class
|
||||
**Extends:** <code>[middleware-stack](#module_middleware-stack)</code>
|
||||
<a name=""></a>
|
||||
|
||||
#### localWebServer.add(middleware) ↩︎
|
||||
**Kind**: instance method of <code>[LocalWebServer](#exp_module_local-web-server--LocalWebServer)</code>
|
||||
**Chainable**
|
||||
**Params**
|
||||
|
||||
- middleware <code>[middleware](#module_middleware-stack--MiddlewareStack..middleware)</code>
|
||||
|
||||
<a name="module_local-web-server--LocalWebServer..collectUserOptions"></a>
|
||||
|
||||
#### LocalWebServer~collectUserOptions()
|
||||
Return default, stored and command-line options combined
|
||||
|
||||
**Kind**: inner method of <code>[LocalWebServer](#exp_module_local-web-server--LocalWebServer)</code>
|
||||
@ -1,193 +0,0 @@
|
||||
[](https://www.npmjs.org/package/local-web-server)
|
||||
[](https://www.npmjs.org/package/local-web-server)
|
||||
[](https://travis-ci.org/75lb/local-web-server)
|
||||
[](https://david-dm.org/75lb/local-web-server)
|
||||
[](https://github.com/feross/standard)
|
||||
[](https://gitter.im/75lb/local-web-server?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
|
||||
***Requires node v4.0.0 or higher. Install the [previous release](https://github.com/75lb/local-web-server/tree/prev) 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](https://github.com/75lb/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.
|
||||
|
||||
## Synopsis
|
||||
local-web-server is a command-line tool. To serve the current directory, run `ws`.
|
||||
|
||||
<pre><code>$ ws --help
|
||||
|
||||
<strong>local-web-server</strong>
|
||||
|
||||
A simple web-server for productive front-end development.
|
||||
|
||||
<strong>Synopsis</strong>
|
||||
|
||||
$ ws [<server options>]
|
||||
$ ws --config
|
||||
$ ws --help
|
||||
|
||||
<strong>Server</strong>
|
||||
|
||||
-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.
|
||||
|
||||
<strong>Misc</strong>
|
||||
|
||||
-h, --help Print these usage instructions.
|
||||
--config Print the stored config.
|
||||
|
||||
Project home: https://github.com/75lb/local-web-server
|
||||
</code></pre>
|
||||
|
||||
## Examples
|
||||
|
||||
For the examples below, we assume we're in a project directory looking like this:
|
||||
|
||||
```sh
|
||||
.
|
||||
├── css
|
||||
│ └── style.css
|
||||
├── index.html
|
||||
└── package.json
|
||||
```
|
||||
|
||||
All paths/routes are specified using [express syntax](http://expressjs.com/guide/routing.html#route-paths). 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:
|
||||
```sh
|
||||
$ ws
|
||||
serving at http://localhost:8000
|
||||
```
|
||||
|
||||
[Example](https://github.com/75lb/local-web-server/tree/master/example/simple).
|
||||
|
||||
### Other usage
|
||||
|
||||
#### Debugging
|
||||
|
||||
Prints information about loaded middleware, arguments, remote proxy fetches etc.
|
||||
```sh
|
||||
$ ws --verbose
|
||||
```
|
||||
|
||||
#### Compression
|
||||
|
||||
Serve gzip-compressed resources, where applicable
|
||||
```sh
|
||||
$ ws --compress
|
||||
```
|
||||
|
||||
#### Disable caching
|
||||
|
||||
Disable etag response headers, forcing resources to be served in full every time.
|
||||
```sh
|
||||
$ ws --no-cache
|
||||
```
|
||||
|
||||
#### Log Visualisation
|
||||
Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/blob/master/doc/visualisation.md).
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
{{#module name="local-web-server"}}
|
||||
{{>body~}}
|
||||
{{>member-index~}}
|
||||
{{>separator~}}
|
||||
{{>members~}}
|
||||
{{/module}}
|
||||
|
||||
* * *
|
||||
|
||||
© 2013-16 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).
|
||||
8
jsdoc2md/api.hbs
Normal file
8
jsdoc2md/api.hbs
Normal file
@ -0,0 +1,8 @@
|
||||
## API Reference
|
||||
|
||||
{{#module name="local-web-server"}}
|
||||
{{>body~}}
|
||||
{{>member-index~}}
|
||||
{{>separator~}}
|
||||
{{>members~}}
|
||||
{{/module}}
|
||||
@ -23,7 +23,7 @@
|
||||
},
|
||||
"scripts": {
|
||||
"test": "tape test/*/*.js",
|
||||
"docs": "jsdoc2md -t jsdoc2md/README.hbs -p list lib/*.js > README.md; echo",
|
||||
"docs": "jsdoc2md -t jsdoc2md/api.hbs -p list lib/*.js > doc/api.md; echo",
|
||||
"cover": "istanbul cover ./node_modules/.bin/tape test/*.js && cat coverage/lcov.info | coveralls && rm -rf coverage; echo"
|
||||
},
|
||||
"repository": "https://github.com/75lb/local-web-server",
|
||||
|
||||
Reference in New Issue
Block a user