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.

222 lines
5.9 KiB

10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 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).
  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. ### Single Page Application
  26. You're building a web app with client-side routing, so mark `index.html` as the SPA.
  27. ```sh
  28. $ ws --spa index.html
  29. ```
  30. 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:
  31. *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.*
  32. ### Access Control
  33. By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist:
  34. ```sh
  35. $ ws --forbid '*.json' '*.yml'
  36. serving at http://localhost:8000
  37. ```
  38. ### URL rewriting
  39. Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule:
  40. ```sh
  41. $ ws --rewrite '/css/style.css -> /build/css/style.css'
  42. ```
  43. Or, more generally (matching any stylesheet under `/css`):
  44. ```sh
  45. $ ws --rewrite '/css/:stylesheet -> /build/css/:stylesheet'
  46. ```
  47. With a deep CSS directory structure it may be easier to mount the entire contents of `/build/css` to the `/css` path:
  48. ```sh
  49. $ ws --rewrite '/css/* -> /build/css/$1'
  50. ```
  51. this rewrites `/css/a` as `/build/css/a`, `/css/a/b/c` as `/build/css/a/b/c` etc.
  52. #### Proxied requests
  53. If the `to` URL contains a remote host, local-web-server will act as a proxy - fetching and responding with the remote resource.
  54. Mount the npm registry locally:
  55. ```sh
  56. $ ws --rewrite '/npm/* -> http://registry.npmjs.org/$1'
  57. ```
  58. Map local requests for repo data to the Github API:
  59. ```sh
  60. $ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name'
  61. ```
  62. ### Stored config
  63. Use the same port and blacklist every time? Persist it to `package.json`:
  64. ```json
  65. {
  66. "name": "example",
  67. "version": "1.0.0",
  68. "local-web-server": {
  69. "port": 8100,
  70. "forbid": "*.json"
  71. }
  72. }
  73. ```
  74. or `.local-web-server.json`
  75. ```json
  76. {
  77. "port": 8100,
  78. "forbid": "*.json"
  79. }
  80. ```
  81. 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.
  82. To inspect stored config, run:
  83. ```sh
  84. $ ws --config
  85. ```
  86. ### Logging
  87. By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use `--log-format`:
  88. ```sh
  89. $ ws --log-format combined
  90. serving at http://localhost:8000
  91. ::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"
  92. ```
  93. The format value supplied is passed directly to [morgan](https://github.com/expressjs/morgan). The exception is `--log-format none` which disables all output.
  94. ### Other usage
  95. #### Debugging
  96. Prints information about loaded middleware, arguments, remote proxy fetches etc.
  97. ```sh
  98. $ ws --verbose
  99. ```
  100. #### Compression
  101. Serve gzip-compressed resources, where applicable
  102. ```sh
  103. $ ws --compress
  104. ```
  105. #### Disable caching
  106. Disable etag response headers, forcing resources to be served in full every time.
  107. ```sh
  108. $ ws --no-cache
  109. ```
  110. #### mime-types
  111. 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:
  112. ```json
  113. {
  114. "mime": {
  115. "text/plain": [ "php", "pl" ]
  116. }
  117. }
  118. ```
  119. #### Log Visualisation
  120. 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).
  121. ## Install
  122. Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`.
  123. ```sh
  124. $ npm install -g local-web-server
  125. ```
  126. This will install the `ws` tool globally. To see the available options, run:
  127. ```sh
  128. $ ws --help
  129. ```
  130. ## Distribute with your project
  131. The standard convention with client-server applications is to add an `npm start` command to launch the server component.
  132. 1\. Install the server as a dev dependency
  133. ```sh
  134. $ npm install local-web-server --save-dev
  135. ```
  136. 2\. Add a `start` command to your `package.json`:
  137. ```json
  138. {
  139. "name": "example",
  140. "version": "1.0.0",
  141. "local-web-server": {
  142. "port": 8100,
  143. "forbid": "\\.json$"
  144. },
  145. "scripts": {
  146. "start": "ws"
  147. }
  148. }
  149. ```
  150. 3\. Document how to build and launch your site
  151. ```sh
  152. $ npm install
  153. $ npm start
  154. serving at http://localhost:8100
  155. ```
  156. ## API Reference
  157. {{#module name="local-web-server"}}
  158. {{>body~}}
  159. {{>member-index~}}
  160. {{>separator~}}
  161. {{>members~}}
  162. {{/module}}
  163. * * *
  164. &copy; 2015 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).