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.

196 lines
4.7 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
10 years ago
11 years ago
12 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
12 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
9 years ago
9 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
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. Some typical use cases. For these examples, assume we're in our site directory, which looks like:
  11. ```sh
  12. $ tree
  13. .
  14. ├── css
  15. │   └── style.css
  16. ├── index.html
  17. └── package.json
  18. ```
  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. With this option, routes with existing files (e.g. `/css/style.css`) will be served normally as static assets. Routes without an existing file (e.g. `/user/1`, `/login` etc.) are passed directly to your SPA. Without this option they would 404.
  31. ### Access Control
  32. Access to all files is allowed, beside those you forbid (e.g. config files):
  33. ```sh
  34. $ ws --forbid .json .yml
  35. serving at http://localhost:8000
  36. ```
  37. ### URL rewriting
  38. When urls don't map to your directory structure, rewrite:
  39. ```sh
  40. $ ws --rewrite /css=>/build/css
  41. ```
  42. Rewrite to remote servers (proxy):
  43. ```sh
  44. $ ws --rewrite "/api => http://api.example.com/api" \
  45. "/npm => http://registry.npmjs.com" \
  46. "/user/:project/repo -> https://api.github.com/repos/:project"
  47. ```
  48. ### Mock Responses
  49. ### Stored config
  50. Always use this port and blacklist? Persist it to the config:
  51. ```json
  52. {
  53. "name": "example",
  54. "version": "1.0.0",
  55. etc,
  56. etc,
  57. "local-web-server": {
  58. "port": 8100,
  59. "forbid": "\\.json$"
  60. }
  61. }
  62. ```
  63. ### Other features
  64. Compression, caching, simple statistics view, log, override mime types.
  65. ## Install
  66. Ensure [node.js](http://nodejs.org) is installed first. Linux/Mac users may need to run the following commands with `sudo`.
  67. ```sh
  68. $ npm install -g local-web-server
  69. ```
  70. ## Distribute with your project
  71. ```sh
  72. $ npm install local-web-server --save-dev
  73. ```
  74. Then add an `start` script to your `package.json` (the standard npm approach):
  75. ```json
  76. {
  77. "name": "my-web-app",
  78. "version": "1.0.0",
  79. "scripts": {
  80. "start": "ws"
  81. }
  82. }
  83. ```
  84. This simplifies a rather specific-looking instruction set like:
  85. ```sh
  86. $ npm install
  87. $ npm install -g local-web-server
  88. $ ws
  89. ```
  90. to the following, server implementation and launch details abstracted away:
  91. ```sh
  92. $ npm install
  93. $ npm start
  94. ```
  95. ## Storing default options
  96. To store per-project options, saving you the hassle of inputting them everytime, store them in the `local-web-server` property of your project's `package.json`:
  97. ```json
  98. {
  99. "name": "my-project",
  100. "version": "0.11.8",
  101. "local-web-server":{
  102. "port": 8100
  103. }
  104. }
  105. ```
  106. Or in a `.local-web-server.json` file stored in the directory you want to serve (typically the root folder of your site):
  107. ```json
  108. {
  109. "port": 8100,
  110. "log-format": "tiny"
  111. }
  112. ```
  113. Or store global defaults in a `.local-web-server.json` file in your home directory.
  114. ```json
  115. {
  116. "port": 3000,
  117. "refresh-rate": 1000
  118. }
  119. ```
  120. All stored defaults are overriden by options supplied at the command line.
  121. To view your stored defaults, run:
  122. ```sh
  123. $ ws --config
  124. ```
  125. ## mime-types
  126. 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:
  127. ```json
  128. {
  129. "mime": {
  130. "text/plain": [ "php", "pl" ]
  131. }
  132. }
  133. ```
  134. ## Use with Google DevTools Workspaces
  135. ## Log Visualisation
  136. Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/wiki/Log-visualisation).
  137. ## API Reference
  138. <a name="module_local-web-server"></a>
  139. ## local-web-server
  140. <a name="exp_module_local-web-server--localWebServer"></a>
  141. ### localWebServer([options]) ⏏
  142. Returns a Koa application
  143. **Kind**: Exported function
  144. | Param | Type | Description |
  145. | --- | --- | --- |
  146. | [options] | <code>object</code> | options |
  147. | [options.forbid] | <code>Array.&lt;regexp&gt;</code> | a list of forbidden routes. |
  148. **Example**
  149. ```js
  150. const localWebServer = require('local-web-server')
  151. ```
  152. * * *
  153. &copy; 2015 Lloyd Brookes <75pound@gmail.com>