Lloyd Brookes
8 years ago
5 changed files with 39 additions and 230 deletions
-
36README.md
-
30doc/api.md
-
193jsdoc2md/README.hbs
-
8jsdoc2md/api.hbs
-
2package.json
@ -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). |
|||
@ -0,0 +1,8 @@ |
|||
## API Reference |
|||
|
|||
{{#module name="local-web-server"}} |
|||
{{>body~}} |
|||
{{>member-index~}} |
|||
{{>separator~}} |
|||
{{>members~}} |
|||
{{/module}} |
|||
Write
Preview
Loading…
Cancel
Save
Reference in new issue