From 22612bbcf4dd8bdbd1b32a422b6ff765855282df Mon Sep 17 00:00:00 2001 From: Lloyd Brookes Date: Mon, 20 Jun 2016 20:32:32 +0100 Subject: [PATCH] docs --- README.md | 102 ++++++--------------- example/README.md | 3 + .../{ => built-in}/forbid/.local-web-server.json | 0 example/{ => built-in}/forbid/admin/blocked.html | 0 example/{ => built-in}/forbid/allowed.html | 0 example/{ => built-in}/forbid/index.html | 0 example/{ => built-in}/forbid/something.php | 0 .../mime-override/.local-web-server.json | 0 example/{ => built-in}/mime-override/something.php | 0 .../mock-async/.local-web-server.json | 0 example/{ => built-in}/mock-async/mocks/delayed.js | 0 example/{ => built-in}/mock/.local-web-server.json | 0 example/{ => built-in}/mock/mocks/five.js | 0 example/{ => built-in}/mock/mocks/stream-self.js | 0 example/{ => built-in}/mock/mocks/user.js | 0 example/{ => built-in}/mock/mocks/users.js | 0 example/{ => built-in}/mock/mocks/users.json | 0 .../{ => built-in}/rewrite/.local-web-server.json | 0 .../{ => built-in}/rewrite/build/styles/style.css | 0 example/{ => built-in}/rewrite/index.html | 0 example/{ => built-in}/simple/css/style.css | 0 example/{ => built-in}/simple/index.html | 0 example/{ => built-in}/simple/package.json | 0 example/{ => built-in}/spa/.local-web-server.json | 0 example/{ => built-in}/spa/css/style.css | 0 example/{ => built-in}/spa/image.jpg | Bin example/{ => built-in}/spa/index.html | 0 .../custom}/cache-control/.local-web-server.json | 0 {extend => example/custom}/cache-control/server.js | 0 .../custom}/live-reload-optional/index.html | 0 .../custom}/live-reload-optional/server.js | 0 {extend => example/custom}/live-reload/index.html | 0 {extend => example/custom}/live-reload/server.js | 0 jsdoc2md/README.hbs | 42 ++++++--- 34 files changed, 59 insertions(+), 88 deletions(-) create mode 100644 example/README.md rename example/{ => built-in}/forbid/.local-web-server.json (100%) rename example/{ => built-in}/forbid/admin/blocked.html (100%) rename example/{ => built-in}/forbid/allowed.html (100%) rename example/{ => built-in}/forbid/index.html (100%) rename example/{ => built-in}/forbid/something.php (100%) rename example/{ => built-in}/mime-override/.local-web-server.json (100%) rename example/{ => built-in}/mime-override/something.php (100%) rename example/{ => built-in}/mock-async/.local-web-server.json (100%) rename example/{ => built-in}/mock-async/mocks/delayed.js (100%) rename example/{ => built-in}/mock/.local-web-server.json (100%) rename example/{ => built-in}/mock/mocks/five.js (100%) rename example/{ => built-in}/mock/mocks/stream-self.js (100%) rename example/{ => built-in}/mock/mocks/user.js (100%) rename example/{ => built-in}/mock/mocks/users.js (100%) rename example/{ => built-in}/mock/mocks/users.json (100%) rename example/{ => built-in}/rewrite/.local-web-server.json (100%) rename example/{ => built-in}/rewrite/build/styles/style.css (100%) rename example/{ => built-in}/rewrite/index.html (100%) rename example/{ => built-in}/simple/css/style.css (100%) rename example/{ => built-in}/simple/index.html (100%) rename example/{ => built-in}/simple/package.json (100%) rename example/{ => built-in}/spa/.local-web-server.json (100%) rename example/{ => built-in}/spa/css/style.css (100%) rename example/{ => built-in}/spa/image.jpg (100%) rename example/{ => built-in}/spa/index.html (100%) rename {extend => example/custom}/cache-control/.local-web-server.json (100%) rename {extend => example/custom}/cache-control/server.js (100%) rename {extend => example/custom}/live-reload-optional/index.html (100%) rename {extend => example/custom}/live-reload-optional/server.js (100%) rename {extend => example/custom}/live-reload/index.html (100%) rename {extend => example/custom}/live-reload/server.js (100%) diff --git a/README.md b/README.md index 24ea340..c261713 100644 --- a/README.md +++ b/README.md @@ -8,28 +8,40 @@ ***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 -A simple, extensible web-server for productive front-end development. Typical use cases: +An application shell for building a simple, command-line web server for productive web development. -* Front-end Development - * Static or Single Page App development - * Re-route paths to local or remote resources - * Efficient, predictable, entity-tag-powered conditional request handling (no need to 'Disable Cache' in DevTools, slowing page-load down) +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 - * Very little configuration, just a few options + * 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) -* Back-end service mocking - * Prototype a web service, microservice, REST API etc. - * Mocks are defined with config (static), or code (dynamic). + * 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. -* Proxy server - * Map local routes to remote servers. Removes CORS pain when consuming remote services. -* HTTPS server - * HTTPS is strictly required by some modern techs (ServiceWorker, Media Capture and Streams etc.) -* File sharing ## Synopsis -local-web-server is a simple command-line tool. To use it, from your project directory run `ws`. +local-web-server is a command-line tool. To serve the current directory, run `ws`. 
$ ws --help
 
@@ -84,7 +96,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)**. To run the example projects linked below, clone the project, move into the example directory specified, run `ws`.
+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
 
@@ -585,63 +597,7 @@ 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]) ⇒ [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 - koa-static config
-        - [.root] string  = "." - root directory
-        - [.options] string - [options](https://github.com/koajs/static#options)
-    - [.serveIndex] object - koa-serve-index config
-        - [.path] string  = "." - root directory
-        - [.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" }
-  ]
-}
-```
-
+ERROR, Cannot find module.
 * * *
 
 © 2013-16 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).
diff --git a/example/README.md b/example/README.md
new file mode 100644
index 0000000..0e12d08
--- /dev/null
+++ b/example/README.md
@@ -0,0 +1,3 @@
+# Examples
+
+Some examples of how to use the built-in middleware and configure custom servers.
diff --git a/example/forbid/.local-web-server.json b/example/built-in/forbid/.local-web-server.json
similarity index 100%
rename from example/forbid/.local-web-server.json
rename to example/built-in/forbid/.local-web-server.json
diff --git a/example/forbid/admin/blocked.html b/example/built-in/forbid/admin/blocked.html
similarity index 100%
rename from example/forbid/admin/blocked.html
rename to example/built-in/forbid/admin/blocked.html
diff --git a/example/forbid/allowed.html b/example/built-in/forbid/allowed.html
similarity index 100%
rename from example/forbid/allowed.html
rename to example/built-in/forbid/allowed.html
diff --git a/example/forbid/index.html b/example/built-in/forbid/index.html
similarity index 100%
rename from example/forbid/index.html
rename to example/built-in/forbid/index.html
diff --git a/example/forbid/something.php b/example/built-in/forbid/something.php
similarity index 100%
rename from example/forbid/something.php
rename to example/built-in/forbid/something.php
diff --git a/example/mime-override/.local-web-server.json b/example/built-in/mime-override/.local-web-server.json
similarity index 100%
rename from example/mime-override/.local-web-server.json
rename to example/built-in/mime-override/.local-web-server.json
diff --git a/example/mime-override/something.php b/example/built-in/mime-override/something.php
similarity index 100%
rename from example/mime-override/something.php
rename to example/built-in/mime-override/something.php
diff --git a/example/mock-async/.local-web-server.json b/example/built-in/mock-async/.local-web-server.json
similarity index 100%
rename from example/mock-async/.local-web-server.json
rename to example/built-in/mock-async/.local-web-server.json
diff --git a/example/mock-async/mocks/delayed.js b/example/built-in/mock-async/mocks/delayed.js
similarity index 100%
rename from example/mock-async/mocks/delayed.js
rename to example/built-in/mock-async/mocks/delayed.js
diff --git a/example/mock/.local-web-server.json b/example/built-in/mock/.local-web-server.json
similarity index 100%
rename from example/mock/.local-web-server.json
rename to example/built-in/mock/.local-web-server.json
diff --git a/example/mock/mocks/five.js b/example/built-in/mock/mocks/five.js
similarity index 100%
rename from example/mock/mocks/five.js
rename to example/built-in/mock/mocks/five.js
diff --git a/example/mock/mocks/stream-self.js b/example/built-in/mock/mocks/stream-self.js
similarity index 100%
rename from example/mock/mocks/stream-self.js
rename to example/built-in/mock/mocks/stream-self.js
diff --git a/example/mock/mocks/user.js b/example/built-in/mock/mocks/user.js
similarity index 100%
rename from example/mock/mocks/user.js
rename to example/built-in/mock/mocks/user.js
diff --git a/example/mock/mocks/users.js b/example/built-in/mock/mocks/users.js
similarity index 100%
rename from example/mock/mocks/users.js
rename to example/built-in/mock/mocks/users.js
diff --git a/example/mock/mocks/users.json b/example/built-in/mock/mocks/users.json
similarity index 100%
rename from example/mock/mocks/users.json
rename to example/built-in/mock/mocks/users.json
diff --git a/example/rewrite/.local-web-server.json b/example/built-in/rewrite/.local-web-server.json
similarity index 100%
rename from example/rewrite/.local-web-server.json
rename to example/built-in/rewrite/.local-web-server.json
diff --git a/example/rewrite/build/styles/style.css b/example/built-in/rewrite/build/styles/style.css
similarity index 100%
rename from example/rewrite/build/styles/style.css
rename to example/built-in/rewrite/build/styles/style.css
diff --git a/example/rewrite/index.html b/example/built-in/rewrite/index.html
similarity index 100%
rename from example/rewrite/index.html
rename to example/built-in/rewrite/index.html
diff --git a/example/simple/css/style.css b/example/built-in/simple/css/style.css
similarity index 100%
rename from example/simple/css/style.css
rename to example/built-in/simple/css/style.css
diff --git a/example/simple/index.html b/example/built-in/simple/index.html
similarity index 100%
rename from example/simple/index.html
rename to example/built-in/simple/index.html
diff --git a/example/simple/package.json b/example/built-in/simple/package.json
similarity index 100%
rename from example/simple/package.json
rename to example/built-in/simple/package.json
diff --git a/example/spa/.local-web-server.json b/example/built-in/spa/.local-web-server.json
similarity index 100%
rename from example/spa/.local-web-server.json
rename to example/built-in/spa/.local-web-server.json
diff --git a/example/spa/css/style.css b/example/built-in/spa/css/style.css
similarity index 100%
rename from example/spa/css/style.css
rename to example/built-in/spa/css/style.css
diff --git a/example/spa/image.jpg b/example/built-in/spa/image.jpg
similarity index 100%
rename from example/spa/image.jpg
rename to example/built-in/spa/image.jpg
diff --git a/example/spa/index.html b/example/built-in/spa/index.html
similarity index 100%
rename from example/spa/index.html
rename to example/built-in/spa/index.html
diff --git a/extend/cache-control/.local-web-server.json b/example/custom/cache-control/.local-web-server.json
similarity index 100%
rename from extend/cache-control/.local-web-server.json
rename to example/custom/cache-control/.local-web-server.json
diff --git a/extend/cache-control/server.js b/example/custom/cache-control/server.js
similarity index 100%
rename from extend/cache-control/server.js
rename to example/custom/cache-control/server.js
diff --git a/extend/live-reload-optional/index.html b/example/custom/live-reload-optional/index.html
similarity index 100%
rename from extend/live-reload-optional/index.html
rename to example/custom/live-reload-optional/index.html
diff --git a/extend/live-reload-optional/server.js b/example/custom/live-reload-optional/server.js
similarity index 100%
rename from extend/live-reload-optional/server.js
rename to example/custom/live-reload-optional/server.js
diff --git a/extend/live-reload/index.html b/example/custom/live-reload/index.html
similarity index 100%
rename from extend/live-reload/index.html
rename to example/custom/live-reload/index.html
diff --git a/extend/live-reload/server.js b/example/custom/live-reload/server.js
similarity index 100%
rename from extend/live-reload/server.js
rename to example/custom/live-reload/server.js
diff --git a/jsdoc2md/README.hbs b/jsdoc2md/README.hbs
index 4f0862c..e28d4ce 100644
--- a/jsdoc2md/README.hbs
+++ b/jsdoc2md/README.hbs
@@ -8,28 +8,40 @@
 ***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
-A simple web-server for productive front-end development. Typical use cases:
+An application shell for building a simple, command-line web server for productive web development.
 
-* Front-end Development
-  * Static or Single Page App development
-  * Re-route paths to local or remote resources
-  * Efficient, predictable, entity-tag-powered conditional request handling (no need to 'Disable Cache' in DevTools, slowing page-load down)
+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
-  * Very little configuration, just a few options
+  * 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)
-* Back-end service mocking
-  * Prototype a web service, microservice, REST API etc.
-  * Mocks are defined with config (static), or code (dynamic).
+  * 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.
-* Proxy server
-  * Map local routes to remote servers. Removes CORS pain when consuming remote services.
-* HTTPS server
-  * HTTPS is strictly required by some modern techs (ServiceWorker, Media Capture and Streams etc.)
-* File sharing
 
 ## Synopsis
-local-web-server is a simple command-line tool. To use it, from your project directory run `ws`.
+local-web-server is a command-line tool. To serve the current directory, run `ws`.
 
 
$ ws --help