diff --git a/README.md b/README.md index c0bee08..45c1c4e 100644 --- a/README.md +++ b/README.md @@ -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,26 +220,61 @@ serving at http://localhost:8100 ## API Reference + +* [local-web-server](#module_local-web-server) + * [localWebServer([options])](#exp_module_local-web-server--localWebServer) ⇒ [KoaApplication](https://github.com/koajs/koa/blob/master/docs/api/index.md#application) ⏏ + * [~rewriteRule](#module_local-web-server--localWebServer..rewriteRule) + -### localWebServer([options]) ⏏ -Returns a Koa application +### localWebServer([options]) ⇒ [KoaApplication](https://github.com/koajs/koa/blob/master/docs/api/index.md#application) ⏏ +Returns a Koa application you can launch or mix into an existing app. **Kind**: Exported function **Params** - [options] object - options - - [.static] object - koajs/static config + - [.static] object - koa-static config - [.root] string - root directory - - [.options] string - options + - [.options] string - [options](https://github.com/koajs/static#options) - [.serveIndex] object - koa-serve-index config - [.path] string - root directory - - [.options] string - options - - [.forbid] Array.<string> - a list of forbidden routes. + - [.options] string - [options](https://github.com/expressjs/serve-index#options) + - [.forbid] Array.<string> - A list of forbidden routes, each route being an [express route-path](http://expressjs.com/guide/routing.html#route-paths). + - [.spa] string - specify an SPA file to catch requests for everything but static assets. + - [.log] object - [morgan](https://github.com/expressjs/morgan) config + - [.format] string - [log format](https://github.com/expressjs/morgan#predefined-formats) + - [.options] object - [options](https://github.com/expressjs/morgan#options) + - [.compress] boolean - Serve gzip-compressed resources, where applicable + - [.mime] object - A list of mime-type overrides, passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine) + - [.rewrite] [Array.<rewriteRule>](#module_local-web-server--localWebServer..rewriteRule) - One or more rewrite rules + - [.verbose] boolean - Print detailed output, useful for debugging **Example** ```js const localWebServer = require('local-web-server') localWebServer().listen(8000) ``` + +#### 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 [localWebServer](#exp_module_local-web-server--localWebServer) +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| from | string | request route | +| to | string | 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" } + ] +} +``` * * * diff --git a/jsdoc2md/README.hbs b/jsdoc2md/README.hbs index 1262a26..846871e 100644 --- a/jsdoc2md/README.hbs +++ b/jsdoc2md/README.hbs @@ -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). diff --git a/lib/cli-options.js b/lib/cli-options.js index c070500..1940a35 100644 --- a/lib/cli-options.js +++ b/lib/cli-options.js @@ -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} ...', @@ -26,7 +26,7 @@ module.exports = { }, { name: 'rewrite', alias: 'r', type: String, multiple: true, typeLabel: '[underline]{expression} ...', - description: "A list of URL rewrite rules, e.g. '/from -> /to'", group: 'server' + description: "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'", group: 'server' }, { name: 'spa', alias: 's', type: String, typeLabel: '[underline]{file}', diff --git a/lib/local-web-server.js b/lib/local-web-server.js index fc450c8..b935642 100644 --- a/lib/local-web-server.js +++ b/lib/local-web-server.js @@ -11,18 +11,27 @@ let debug module.exports = localWebServer /** - * Returns a Koa application + * Returns a Koa application you can launch or mix into an existing app. * * @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 + * @return {external:KoaApplication} * @example * const localWebServer = require('local-web-server') * localWebServer().listen(8000) @@ -244,3 +253,27 @@ function mockResponses (options) { 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 + */ + +/** + * @external KoaApplication + * @see https://github.com/koajs/koa/blob/master/docs/api/index.md#application + */ diff --git a/package.json b/package.json index bac763d..a08818f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "local-web-server", - "version": "1.0.0-alpha.3", + "version": "1.0.0-alpha.4", "description": "A simple web-server for productive front-end development", "bin": { "ws": "./bin/cli.js"