Lloyd Brookes
9 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