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

docs

Browse Source
This commit is contained in:
Lloyd Brookes
2015-11-19 10:01:04 +00:00
parent aab1f04a2f
commit bbd0d9fbe6
4 changed files with 93 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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 - [.options] <code>string</code> - [options](https://github.com/expressjs/serve-index#options)
- [.forbid] <code>Array.&lt;string&gt;</code> - a list of forbidden routes. - [.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.serveIndex.options] {string} - [options](https://github.com/expressjs/serve-index#options)
* @param [options.forbid] {string[]} - a list of forbidden routes. * @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
*/