wpstudio
/
hiring-test-one
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

docs

master
Lloyd Brookes 9 years ago
parent
aab1f04a2f
commit
bbd0d9fbe6
4 changed files with 93 additions and 11 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 55
      README.md
  2. 12
      jsdoc2md/README.hbs
  3. 2
      lib/cli-options.js
  4. 35
      lib/local-web-server.js

55
README.md
View File

@ -20,7 +20,7 @@ For the examples below, we assume we're in a project directory looking like this
└── package.json └── package.json
``` ```
All paths/routes are specified using [express syntax](http://expressjs.com/guide/routing.html#route-paths).
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 ### Static site
@ -30,6 +30,8 @@ $ ws
serving at http://localhost:8000 serving at http://localhost:8000
``` ```
[Example](https://github.com/75lb/local-web-server/tree/master/example/simple).
### Single Page Application ### Single Page Application
You're building a web app with client-side routing, so mark `index.html` as the SPA. You're building a web app with client-side routing, so mark `index.html` as the SPA.
@ -41,6 +43,8 @@ By default, typical SPA urls (e.g. `/user/1`, `/login`) would return `404 Not Fo
*If a static file at the requested path exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then serve the specified SPA and handle the route client-side.* *If a static file at the requested path exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then serve the specified SPA and handle the route client-side.*
[Example](https://github.com/75lb/local-web-server/tree/master/example/spa).
### Access Control ### Access Control
By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist: By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist:
@ -49,6 +53,8 @@ $ ws --forbid '*.json' '*.yml'
serving at http://localhost:8000 serving at http://localhost:8000
``` ```
[Example](https://github.com/75lb/local-web-server/tree/master/example/forbid).
### URL rewriting ### URL rewriting
Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule: Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule:
@ -86,6 +92,8 @@ Map local requests for repo data to the Github API:
$ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name' $ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name'
``` ```
[Example](https://github.com/75lb/local-web-server/tree/master/example/rewrite).
### Stored config ### Stored config
Use the same port and blacklist every time? Persist it to `package.json`: Use the same port and blacklist every time? Persist it to `package.json`:
@ -160,6 +168,8 @@ You can set additional mime-type/extension mappings, or override the defaults by
} }
``` ```
[Example](https://github.com/75lb/local-web-server/tree/master/example/mime-override).
#### Log Visualisation #### 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). 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).
@ -210,6 +220,11 @@ serving at http://localhost:8100
## API Reference ## API Reference
* [local-web-server](#module_local-web-server)
* [localWebServer([options])](#exp_module_local-web-server--localWebServer) ⏏
* [~rewriteRule](#module_local-web-server--localWebServer..rewriteRule)
<a name="exp_module_local-web-server--localWebServer"></a> <a name="exp_module_local-web-server--localWebServer"></a>
### localWebServer([options]) ⏏ ### localWebServer([options]) ⏏
Returns a Koa application Returns a Koa application
@ -217,19 +232,49 @@ Returns a Koa application
**Kind**: Exported function **Kind**: Exported function
**Params** **Params**
- [options] <code>object</code> - options - [options] <code>object</code> - options
- [.static] <code>object</code> - koajs/static config
- [.static] <code>object</code> - koa-static config
- [.root] <code>string</code> - root directory - [.root] <code>string</code> - root directory
- [.options] <code>string</code> - options
- [.options] <code>string</code> - [options](https://github.com/koajs/static#options)
- [.serveIndex] <code>object</code> - koa-serve-index config - [.serveIndex] <code>object</code> - koa-serve-index config
- [.path] <code>string</code> - root directory - [.path] <code>string</code> - root directory
- [.options] <code>string</code> - options
- [.forbid] <code>Array.&lt;string&gt;</code> - a list of forbidden routes.
- [.options] <code>string</code> - [options](https://github.com/expressjs/serve-index#options)
- [.forbid] <code>Array.&lt;string&gt;</code> - A list of forbidden routes, each route being an [express route-path](http://expressjs.com/guide/routing.html#route-paths).
- [.spa] <code>string</code> - specify an SPA file to catch requests for everything but static assets.
- [.log] <code>object</code> - [morgan](https://github.com/expressjs/morgan) config
- [.format] <code>string</code> - [log format](https://github.com/expressjs/morgan#predefined-formats)
- [.options] <code>object</code> - [options](https://github.com/expressjs/morgan#options)
- [.compress] <code>boolean</code> - Serve gzip-compressed resources, where applicable
- [.mime] <code>object</code> - A list of mime-type overrides, passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine)
- [.rewrite] <code>[Array.&lt;rewriteRule&gt;](#module_local-web-server--localWebServer..rewriteRule)</code> - One or more rewrite rules
- [.verbose] <code>boolean</code> - Print detailed output, useful for debugging
**Example** **Example**
```js ```js
const localWebServer = require('local-web-server') const localWebServer = require('local-web-server')
localWebServer().listen(8000) localWebServer().listen(8000)
``` ```
<a name="module_local-web-server--localWebServer..rewriteRule"></a>
#### localWebServer~rewriteRule
The `from` and `to` routes are specified using [express route-paths](http://expressjs.com/guide/routing.html#route-paths)
**Kind**: inner typedef of <code>[localWebServer](#exp_module_local-web-server--localWebServer)</code>
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| from | <code>string</code> | request route |
| to | <code>string</code> | target route |
**Example**
```json
{
"rewrite": [
{ "from": "/css/*", "to": "/build/styles/$1" },
{ "from": "/npm/*", "to": "http://registry.npmjs.org/$1" },
{ "from": "/:user/repos/:name", "to": "https://api.github.com/repos/:user/:name" }
]
}
```
* * * * * *

12
jsdoc2md/README.hbs
View File

@ -20,7 +20,7 @@ For the examples below, we assume we're in a project directory looking like this
└── package.json └── package.json
``` ```
All paths/routes are specified using [express syntax](http://expressjs.com/guide/routing.html#route-paths).
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 ### Static site
@ -30,6 +30,8 @@ $ ws
serving at http://localhost:8000 serving at http://localhost:8000
``` ```
[Example](https://github.com/75lb/local-web-server/tree/master/example/simple).
### Single Page Application ### Single Page Application
You're building a web app with client-side routing, so mark `index.html` as the SPA. You're building a web app with client-side routing, so mark `index.html` as the SPA.
@ -41,6 +43,8 @@ By default, typical SPA urls (e.g. `/user/1`, `/login`) would return `404 Not Fo
*If a static file at the requested path exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then serve the specified SPA and handle the route client-side.* *If a static file at the requested path exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then serve the specified SPA and handle the route client-side.*
[Example](https://github.com/75lb/local-web-server/tree/master/example/spa).
### Access Control ### Access Control
By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist: By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist:
@ -49,6 +53,8 @@ $ ws --forbid '*.json' '*.yml'
serving at http://localhost:8000 serving at http://localhost:8000
``` ```
[Example](https://github.com/75lb/local-web-server/tree/master/example/forbid).
### URL rewriting ### URL rewriting
Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule: Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule:
@ -86,6 +92,8 @@ Map local requests for repo data to the Github API:
$ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name' $ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name'
``` ```
[Example](https://github.com/75lb/local-web-server/tree/master/example/rewrite).
### Stored config ### Stored config
Use the same port and blacklist every time? Persist it to `package.json`: Use the same port and blacklist every time? Persist it to `package.json`:
@ -160,6 +168,8 @@ You can set additional mime-type/extension mappings, or override the defaults by
} }
``` ```
[Example](https://github.com/75lb/local-web-server/tree/master/example/mime-override).
#### Log Visualisation #### 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). 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).

2
lib/cli-options.js
View File

@ -14,7 +14,7 @@ module.exports = {
}, },
{ {
name: 'compress', alias: 'c', type: Boolean, name: 'compress', alias: 'c', type: Boolean,
description: 'Enable gzip compression, reduces bandwidth.', group: 'server'
description: 'Serve gzip-compressed resources, where applicable', group: 'server'
}, },
{ {
name: 'forbid', alias: 'b', type: String, multiple: true, typeLabel: '[underline]{path} ...', name: 'forbid', alias: 'b', type: String, multiple: true, typeLabel: '[underline]{path} ...',

35
lib/local-web-server.js
View File

@ -17,13 +17,21 @@ module.exports = localWebServer
* Returns a Koa application * Returns a Koa application
* *
* @param [options] {object} - options * @param [options] {object} - options
* @param [options.static] {object} - koajs/static config
* @param [options.static] {object} - koa-static config
* @param [options.static.root] {string} - root directory * @param [options.static.root] {string} - root directory
* @param [options.static.options] {string} - options
* @param [options.static.options] {string} - [options](https://github.com/koajs/static#options)
* @param [options.serveIndex] {object} - koa-serve-index config * @param [options.serveIndex] {object} - koa-serve-index config
* @param [options.serveIndex.path] {string} - root directory * @param [options.serveIndex.path] {string} - root directory
* @param [options.serveIndex.options] {string} - options
* @param [options.forbid] {string[]} - a list of forbidden routes.
* @param [options.serveIndex.options] {string} - [options](https://github.com/expressjs/serve-index#options)
* @param [options.forbid] {string[]} - A list of forbidden routes, each route being an [express route-path](http://expressjs.com/guide/routing.html#route-paths).
* @param [options.spa] {string} - specify an SPA file to catch requests for everything but static assets.
* @param [options.log] {object} - [morgan](https://github.com/expressjs/morgan) config
* @param [options.log.format] {string} - [log format](https://github.com/expressjs/morgan#predefined-formats)
* @param [options.log.options] {object} - [options](https://github.com/expressjs/morgan#options)
* @param [options.compress] {boolean} - Serve gzip-compressed resources, where applicable
* @param [options.mime] {object} - A list of mime-type overrides, passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine)
* @param [options.rewrite] {module:local-web-server~rewriteRule[]} - One or more rewrite rules
* @param [options.verbose] {boolean} - Print detailed output, useful for debugging
* *
* @alias module:local-web-server * @alias module:local-web-server
* @example * @example
@ -213,3 +221,22 @@ function blacklist (forbid) {
process.on('unhandledRejection', (reason, p) => { process.on('unhandledRejection', (reason, p) => {
throw reason throw reason
}) })
/**
* The `from` and `to` routes are specified using [express route-paths](http://expressjs.com/guide/routing.html#route-paths)
*
* @example
* ```json
* {
* "rewrite": [
* { "from": "/css/*", "to": "/build/styles/$1" },
* { "from": "/npm/*", "to": "http://registry.npmjs.org/$1" },
* { "from": "/:user/repos/:name", "to": "https://api.github.com/repos/:user/:name" }
* ]
* }
* ```
*
* @typedef rewriteRule
* @property from {string} - request route
* @property to {string} - target route
*/
Write Preview
Loading…
Cancel
Save