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
Split 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
```
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
@ -30,6 +30,8 @@ $ ws
serving at http://localhost:8000
```
[Example](https://github.com/75lb/local-web-server/tree/master/example/simple).
### Single Page Application
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.*
[Example](https://github.com/75lb/local-web-server/tree/master/example/spa).
### Access Control
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
```
[Example](https://github.com/75lb/local-web-server/tree/master/example/forbid).
### 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:
@ -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'
```
[Example](https://github.com/75lb/local-web-server/tree/master/example/rewrite).
### Stored config
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
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
* [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>
### localWebServer([options]) ⏏
Returns a Koa application
@ -217,19 +232,49 @@ Returns a Koa application
**Kind**: Exported function
**Params**
- [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
- [.options] <code>string</code> - options
- [.options] <code>string</code> - [options](https://github.com/koajs/static#options)
- [.serveIndex] <code>object</code> - koa-serve-index config
- [.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**
```js
const localWebServer = require('local-web-server')
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
```
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
@ -30,6 +30,8 @@ $ ws
serving at http://localhost:8000
```
[Example](https://github.com/75lb/local-web-server/tree/master/example/simple).
### Single Page Application
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.*
[Example](https://github.com/75lb/local-web-server/tree/master/example/spa).
### Access Control
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
```
[Example](https://github.com/75lb/local-web-server/tree/master/example/forbid).
### 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:
@ -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'
```
[Example](https://github.com/75lb/local-web-server/tree/master/example/rewrite).
### Stored config
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
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,
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} ...',

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

@ -17,13 +17,21 @@ module.exports = localWebServer
* Returns a Koa application
*
* @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.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.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
* @example
@ -213,3 +221,22 @@ function blacklist (forbid) {
process.on('unhandledRejection', (reason, p) => {
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