You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

232 lines
6.4 KiB

9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
  1. [![view on npm](http://img.shields.io/npm/v/local-web-server.svg)](https://www.npmjs.org/package/local-web-server)
  2. [![npm module downloads](http://img.shields.io/npm/dt/local-web-server.svg)](https://www.npmjs.org/package/local-web-server)
  3. [![Build Status](https://travis-ci.org/75lb/local-web-server.svg?branch=master)](https://travis-ci.org/75lb/local-web-server)
  4. [![Dependency Status](https://david-dm.org/75lb/local-web-server.svg)](https://david-dm.org/75lb/local-web-server)
  5. [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/feross/standard)
  6. # local-web-server
  7. A simple web-server for productive front-end development.
  8. **Requires node v4.0.0 or higher**.
  9. ## Synopsis
  10. For the examples below, we assume we're in a project directory looking like this:
  11. ```sh
  12. .
  13. ├── css
  14. │   └── style.css
  15. ├── index.html
  16. └── package.json
  17. ```
  18. 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`.
  19. ### Static site
  20. Fire up your static site on the default port:
  21. ```sh
  22. $ ws
  23. serving at http://localhost:8000
  24. ```
  25. [Example](https://github.com/75lb/local-web-server/tree/master/example/simple).
  26. ### Single Page Application
  27. You're building a web app with client-side routing, so mark `index.html` as the SPA.
  28. ```sh
  29. $ ws --spa index.html
  30. ```
  31. By default, typical SPA urls (e.g. `/user/1`, `/login`) would return `404 Not Found` as a file does not exist with that path. By marking `index.html` as the SPA you create this rule:
  32. *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.*
  33. [Example](https://github.com/75lb/local-web-server/tree/master/example/spa).
  34. ### Access Control
  35. By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist:
  36. ```sh
  37. $ ws --forbid '*.json' '*.yml'
  38. serving at http://localhost:8000
  39. ```
  40. [Example](https://github.com/75lb/local-web-server/tree/master/example/forbid).
  41. ### URL rewriting
  42. Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule:
  43. ```sh
  44. $ ws --rewrite '/css/style.css -> /build/css/style.css'
  45. ```
  46. Or, more generally (matching any stylesheet under `/css`):
  47. ```sh
  48. $ ws --rewrite '/css/:stylesheet -> /build/css/:stylesheet'
  49. ```
  50. With a deep CSS directory structure it may be easier to mount the entire contents of `/build/css` to the `/css` path:
  51. ```sh
  52. $ ws --rewrite '/css/* -> /build/css/$1'
  53. ```
  54. this rewrites `/css/a` as `/build/css/a`, `/css/a/b/c` as `/build/css/a/b/c` etc.
  55. #### Proxied requests
  56. If the `to` URL contains a remote host, local-web-server will act as a proxy - fetching and responding with the remote resource.
  57. Mount the npm registry locally:
  58. ```sh
  59. $ ws --rewrite '/npm/* -> http://registry.npmjs.org/$1'
  60. ```
  61. Map local requests for repo data to the Github API:
  62. ```sh
  63. $ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name'
  64. ```
  65. [Example](https://github.com/75lb/local-web-server/tree/master/example/rewrite).
  66. ### Stored config
  67. Use the same port and blacklist every time? Persist it to `package.json`:
  68. ```json
  69. {
  70. "name": "example",
  71. "version": "1.0.0",
  72. "local-web-server": {
  73. "port": 8100,
  74. "forbid": "*.json"
  75. }
  76. }
  77. ```
  78. or `.local-web-server.json`
  79. ```json
  80. {
  81. "port": 8100,
  82. "forbid": "*.json"
  83. }
  84. ```
  85. local-web-server will merge and use all config found, searching from the current directory upward. In the case both `package.json` and `.local-web-server.json` config is found in the same directory, `.local-web-server.json` will take precedence. Command-line options take precedence over all.
  86. To inspect stored config, run:
  87. ```sh
  88. $ ws --config
  89. ```
  90. ### Logging
  91. By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use `--log-format`:
  92. ```sh
  93. $ ws --log-format combined
  94. serving at http://localhost:8000
  95. ::1 - - [16/Nov/2015:11:16:52 +0000] "GET / HTTP/1.1" 200 12290 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2562.0 Safari/537.36"
  96. ```
  97. The format value supplied is passed directly to [morgan](https://github.com/expressjs/morgan). The exception is `--log-format none` which disables all output.
  98. ### Other usage
  99. #### Debugging
  100. Prints information about loaded middleware, arguments, remote proxy fetches etc.
  101. ```sh
  102. $ ws --verbose
  103. ```
  104. #### Compression
  105. Serve gzip-compressed resources, where applicable
  106. ```sh
  107. $ ws --compress
  108. ```
  109. #### Disable caching
  110. Disable etag response headers, forcing resources to be served in full every time.
  111. ```sh
  112. $ ws --no-cache
  113. ```
  114. #### mime-types
  115. You can set additional mime-type/extension mappings, or override the defaults by setting a `mime` value in the stored config. This value is passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine). Example:
  116. ```json
  117. {
  118. "mime": {
  119. "text/plain": [ "php", "pl" ]
  120. }
  121. }
  122. ```
  123. [Example](https://github.com/75lb/local-web-server/tree/master/example/mime-override).
  124. #### Log Visualisation
  125. 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).
  126. ## Install
  127. Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`.
  128. ```sh
  129. $ npm install -g local-web-server
  130. ```
  131. This will install the `ws` tool globally. To see the available options, run:
  132. ```sh
  133. $ ws --help
  134. ```
  135. ## Distribute with your project
  136. The standard convention with client-server applications is to add an `npm start` command to launch the server component.
  137. 1\. Install the server as a dev dependency
  138. ```sh
  139. $ npm install local-web-server --save-dev
  140. ```
  141. 2\. Add a `start` command to your `package.json`:
  142. ```json
  143. {
  144. "name": "example",
  145. "version": "1.0.0",
  146. "local-web-server": {
  147. "port": 8100,
  148. "forbid": "\\.json$"
  149. },
  150. "scripts": {
  151. "start": "ws"
  152. }
  153. }
  154. ```
  155. 3\. Document how to build and launch your site
  156. ```sh
  157. $ npm install
  158. $ npm start
  159. serving at http://localhost:8100
  160. ```
  161. ## API Reference
  162. {{#module name="local-web-server"}}
  163. {{>body~}}
  164. {{>member-index~}}
  165. {{>separator~}}
  166. {{>members~}}
  167. {{/module}}
  168. * * *
  169. &copy; 2015 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).