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.

218 lines
5.6 KiB

9 years ago
11 years ago
11 years ago
10 years ago
12 years ago
11 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
10 years ago
11 years ago
12 years ago
9 years ago
9 years ago
9 years ago
9 years ago
11 years ago
9 years ago
9 years ago
11 years ago
11 years ago
9 years ago
11 years ago
9 years ago
11 years ago
11 years ago
11 years ago
9 years ago
11 years ago
9 years ago
11 years ago
12 years ago
10 years ago
9 years ago
9 years ago
11 years ago
9 years ago
11 years ago
9 years ago
11 years ago
10 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, 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. ### Static site
  19. Fire up your static site on the default port:
  20. ```sh
  21. $ ws
  22. serving at http://localhost:8000
  23. ```
  24. ### Single Page Application
  25. You're building a web app with client-side routing, so mark `index.html` as the SPA.
  26. ```sh
  27. $ ws --spa index.html
  28. ```
  29. 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:
  30. *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.*
  31. ### Access Control
  32. By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist:
  33. ```sh
  34. $ ws --forbid '*.json' '*.yml'
  35. serving at http://localhost:8000
  36. ```
  37. [Path syntax](http://expressjs.com/guide/routing.html#route-paths)
  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 '/projects/:user/repos/:name -> https://api.github.com/repos/:user/:name'
  61. ```
  62. ### Stored config
  63. Always use this port and blacklist? 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. ### Logging
  82. By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use `--log-format`:
  83. ```sh
  84. $ ws --log-format combined
  85. serving at http://localhost:8000
  86. ::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"
  87. ```
  88. [morgan](https://github.com/expressjs/morgan)
  89. ### Other features
  90. Serve gzip-compressed resources, where applicable
  91. ```sh
  92. $ ws --compress
  93. ```
  94. Disable etag-based caching
  95. ```sh
  96. $ ws --no-cache
  97. ```
  98. ### Log Visualisation
  99. Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/wiki/Log-visualisation).
  100. ## Install
  101. Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`.
  102. ```sh
  103. $ npm install -g local-web-server
  104. ```
  105. This will install the `ws` tool globally. To see the available options, run:
  106. ```sh
  107. $ ws --help
  108. ```
  109. ## Distribute with your project
  110. The standard convention with client-server applications is to add an `npm start` command to launch the server component.
  111. 1\. Install the server as a dev dependency
  112. ```sh
  113. $ npm install local-web-server --save-dev
  114. ```
  115. 2\. Add a `start` command to your `package.json`:
  116. ```json
  117. {
  118. "name": "example",
  119. "version": "1.0.0",
  120. "local-web-server": {
  121. "port": 8100,
  122. "forbid": "\\.json$"
  123. },
  124. "scripts": {
  125. "start": "ws"
  126. }
  127. }
  128. ```
  129. 3\. Document how to build and launch your site
  130. ```sh
  131. $ npm install
  132. $ npm start
  133. serving at http://localhost:8100
  134. ```
  135. ## mime-types
  136. You can set additional mime-type/extension mappings, or override the defaults by setting a `mime` value in your local config. This value is passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine). Example:
  137. ```json
  138. {
  139. "mime": {
  140. "text/plain": [ "php", "pl" ]
  141. }
  142. }
  143. ```
  144. ## API Reference
  145. <a name="module_local-web-server"></a>
  146. ## local-web-server
  147. <a name="exp_module_local-web-server--localWebServer"></a>
  148. ### localWebServer([options]) ⏏
  149. Returns a Koa application
  150. **Kind**: Exported function
  151. | Param | Type | Description |
  152. | --- | --- | --- |
  153. | [options] | <code>object</code> | options |
  154. | [options.forbid] | <code>Array.&lt;regexp&gt;</code> | a list of forbidden routes. |
  155. **Example**
  156. ```js
  157. const localWebServer = require('local-web-server')
  158. localWebServer().listen(8000)
  159. ```
  160. * * *
  161. &copy; 2015 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).