www.aleph1.co.uk Git - yaffs-website/blob - node_modules/livereload-js/README.md

   1 LiveReload.js
   2 =============
   3
   4 What is LiveReload?
   5 -------------------
   6
   7 LiveReload is a tool for web developers and designers. See [livereload.com](http://livereload.com) for more info.
   8
   9 To use LiveReload, you need a client (this script) in your browser and a server running on your development machine.
  10
  11 This repository (livereload.js) implements the client side of the protocol. The client connects to a LiveReload server via web sockets and listens for incoming change notifications. When a CSS or an image file is modified, it is live-refreshed without reloading the page. When any other file is modified, the page is reloaded.
  12
  13 The server notifies the client whenever a change is made. Available servers are:
  14
  15 * [LiveReload app for Mac](http://livereload.com/)
  16 * [rack-livereload](https://github.com/johnbintz/rack-livereload)
  17 * [guard-livereload](https://github.com/guard/guard-livereload)
  18 * [grunt-contrib-watch](https://github.com/gruntjs/grunt-contrib-watch)
  19 * more available on Google :-)
  20 * you can even write your own; refer to the [LiveReload protocol](http://help.livereload.com/kb/ecosystem/livereload-protocol)
  21
  22 If you are a web developer looking to _use_ LiveReload, you should refer to your LiveReload server/app/tool's documentation, rather that this repository. **You should use the copy of livereload.js script bundled with your server**, because it's guaranteed to be compatible, and may be customized for that server.
  23
  24 Most LiveReload server vendors will serve livereload.js on the LiveReload port. When your server is running, you can typically access the script at `http://0.0.0.0:35729/livereload.js`.
  25
  26 Please read on *only* if you are:
  27
  28 * using a server that doesn't document the usage of livereload.js
  29 * interested in hacking on livereload.js or want to understand it better
  30 * developing a LiveReload server
  31
  32
  33 What is livereload.js?
  34 ----------------------
  35
  36 This repository contains a JavaScript file implementing the client side of the LiveReload protocol. It gets change notifications from a LiveReload server and applies them to the browser.
  37
  38 If you are **developing** a LiveReload server, see [dist/livereload.js](https://github.com/livereload/livereload-js/raw/master/dist/livereload.js) for the latest version built using the sources in this repository. We require LiveReload server vendors to distribute livereload.js as part of their apps or tools.
  39
  40 An old version of this script is also bundled with the LiveReload browser extensions, but it's not getting updated and only serves for compatibility with very old clients.
  41
  42 Features:
  43
  44 * Live CSS reloading
  45 * Full page reloading
  46 * Protocol, WebSocket communication
  47 * CSS `@import` support
  48 * Live image reloading (`<img src="..." />`, `background-image` and `border-image` properties, both inline and in stylesheets)
  49 * Live, in-browser LESS.js reloading
  50
  51 Would love, but doesn't seem possible:
  52
  53 * live JS reloading
  54
  55
  56 Installing using Bower
  57 ----------------------
  58
  59 This script is published on Bower. (But, to reiterate: the preferred method is to avoid installing it altogether, and instead use the one bundled with your LiveReload server/app/tool.)
  60
  61 Installation:
  62
  63     bower install livereload-js --save-dev
  64
  65 This gives you a component containing a single script file, `dist/livereload.js`.
  66
  67
  68 Installing using npm and Browserify
  69 -----------------------------------
  70
  71 Including livereload.js into your Browserify bundle probably makes no sense, because livereload.js isn't something you would ship to production.
  72
  73 But if you insist _and_ you know what you're doing, you can install LiveReload via npm:
  74
  75     npm install livereload-js --save
  76
  77 and then add this to your bundle:
  78
  79     window.LiveReloadOptions = { host: 'localhost' };
  80     require('livereload-js');
  81
  82 Note that livereload-js package uses `window` and `document` globals, so won't run under Node.js environment.
  83
  84 The reason you need to specify `LiveReloadOptions` is that `livereload.js` won't be able to find its `<script>` tag and would normally bail out with an error message.
  85
  86
  87 Using livereload.js
  88 -------------------
  89
  90 This script is meant to be included into the web pages you want to monitor, like this:
  91
  92     <script src="http://localhost:35729/livereload.js"></script>
  93
  94 LiveReload 2 server listens on port `35729` and serves livereload.js over HTTP (besides speaking the web socket protocol on the same port).
  95
  96 A slightly smarter way is to use the host name of the current page, assuming that it is being served from the same computer. This approach enables LiveReload when viewing the web page from other devices on the network:
  97
  98 ```html
  99 <script>document.write('<script src="http://'
 100     + location.host.split(':')[0]
 101     + ':35729/livereload.js"></'
 102     + 'script>')</script>
 103 ```
 104
 105
 106 However, since `location.host` is empty for `file:` URLs, we need to account for that:
 107
 108 ```html
 109 <script>document.write('<script src="http://'
 110     + (location.host || 'localhost').split(':')[0]
 111     + ':35729/livereload.js"></'
 112     + 'script>')</script>
 113 ```
 114
 115
 116 LiveReload.js finds a `script` tag that includes `…/livereload.js` and uses it to determine the hostname/port to connect to. It also understands some options from the query string: `host`, `port`, `snipver`, `mindelay` and `maxdelay`.
 117
 118 `snipver` specifies a version of the snippet, so that we can warn when the snippet needs to be updated. The currently recommended `snipver` is version 1:
 119
 120 ```html
 121 <script>document.write('<script src="http://'
 122     + (location.host || 'localhost').split(':')[0]
 123     + ':35729/livereload.js?snipver=1"></'
 124     + 'script>')</script>
 125 ```
 126
 127
 128 Additionally, you might want to specify `mindelay` and `maxdelay`, which is minimum and maximum reconnection delay in milliseconds (defaulting to `1000` and `60000`).
 129
 130 Alternatively, instead of loading livereload.js from the LiveReload server, you might want to include it from a different URL. In this case, add a `host` parameter to override the host name. For example:
 131
 132 ```html
 133 <script src="https://github.com/livereload/livereload-js/raw/master/dist/livereload.js?host=localhost"></script>
 134 ```
 135
 136
 137 Options
 138 -------
 139
 140 Options can either be specified as query parameters of the `<script src="..../livereload.js">` tag's source URL, or as a global `window.LiveReloadOptions` dictionary. If the dictionary is specified, `livereload.js` does not even try looking for its `<script>` tag.
 141
 142 The set of supported options is the same for both methods:
 143
 144 * `host`: the host that runs a LiveReload server; required if specifying `LiveReloadOptions`, otherwise will be autodetected as the origin of the `<script>` tag
 145 * `port`: optional server port override
 146 * `mindelay`, `maxdelay`: range of reconnection delays (if `livereload.js` cannot connect to the server, it will attempt to reconnect with increasing delays); defaults to 1,000 ms minimum and 60,000 ms maximum
 147 * `handshake_timeout`: timeout for a protocol handshake to be completed after a connection attempt; mostly only needed if you're running an interactive debugger on your web socket server
 148
 149
 150 Issues & Limitations
 151 --------------------
 152
 153 **Serving livereload.js outside of the domain root.** Livereload.js expects to be served from the domain root (i.e. `http://myawesomeblog.com/livereload.js`). Serving from outside the domain root is possible, just add the `host` parameter to the `script` tag (see parameters documentation above).
 154
 155 **Live reloading of imported stylesheets has a 200ms lag.** Modifying a CSS `@import` rule to reference a not-yet-cached file causes WebKit to lose all document styles, so we have to apply a workaround that causes a lag.
 156
 157 Our workaround is to add a temporary `<link />` element for the imported stylesheet we're trying to reload, wait 200ms to make sure WebKit loads the new file, then remove `<link />` and recreate the `@import` rule. This prevents a flash of unstyled content. (We also wait 200 more milliseconds and recreate the `@import` rule again, in case those initial 200ms were not enough.)
 158
 159 **Live image reloading is limited to `<img src="..." />`, `background-image` and `border-image` styles.** Any other places where images can be mentioned?
 160
 161 **Live image reloading is limited to `jpg`, `jpeg`, `gif`, and `png` extensions.** Maybe need to add `svg` there? Anything else?
 162
 163
 164 Communicating with livereload.js
 165 --------------------------------
 166
 167 It is possible to communicate with a running LiveReload script using DOM events:
 168
 169 * fire `LiveReloadShutDown` event on `document` to make LiveReload disconnect and go away
 170 * listen for `LiveReloadConnect` event on `document` to learn when the connection is established
 171 * listen for `LiveReloadDisconnect` event on `document` to learn when the connection is interrupted (or fails to be established)
 172
 173 The `LiveReload` object is also exposed as `window.LiveReload`, with `LiveReload.disconnect()`, `LiveReload.connect()`, and `LiveReload.shutDown()` available. However, I'm not yet sure if I want to keep this API, so consider it non-contractual. (And please tell me if you have a use for it!)
 174
 175
 176 Having trouble?
 177 ---------------
 178
 179 To enable debugging output to console, append `?LR-verbose` to your URL.
 180
 181
 182 Hacking on LiveReload.js
 183 ------------------------
 184
 185 Requirements:
 186
 187 * Node.js with npm
 188 * Grunt (`npm install grunt-cli`)
 189
 190 To install additional prerequisites:
 191
 192     npm install
 193
 194 To build:
 195
 196     grunt build
 197
 198 To run tests:
 199
 200     grunt
 201
 202 Manual testing: open files in `test/html/*` in various browsers, make some changes and make sure they are applied.
 203
 204 Testing the Browserify usage scenario: `grunt browserify:test`, then perform manual testing of `test/html/browserified/`.
 205
 206
 207 Releasing a new version
 208 -----------------------
 209
 210 1. Update the version number in `package.json`.
 211
 212 1. Run `rake version` to update the version numbers in all other files, using the one from `package.json`.
 213
 214 1. Run `grunt`.
 215
 216 1. Do some manual testing.
 217
 218 1. Tag the version in Git: `rake tag` then `git push --tags`.
 219
 220 1. `npm publish`
 221
 222
 223 License
 224 -------
 225
 226 livereload-js is available under the MIT license. See the LICENSE file for details.
 227
 228
 229 Version history
 230 ---------------
 231
 232 2.2.1 (Jan 17, 2015)
 233
 234 * npm fix: actually include `/lib` in the package
 235
 236 2.2.0 (Jan 16, 2015)
 237
 238 * the first version stitched with Browserify; everything seems to work, but 2.1.0 is available just in case
 239 * switched the build system to Grunt
 240
 241 2.1.0 (Jan 16, 2015)
 242
 243 * use case-insensitive matching for `rel` attribute in `<link rel="stylesheet">` tags, to accomodate legacy Rails versions
 244 * avoid usage of `console` when it's not definited
 245 * some README changes
 246
 247 2.0.8 (May 22, 2012)
 248
 249 * Fix live CSS refresh to work with prefixfree
 250 * Correctly trigger removal of old `<link>` tags
 251
 252 (older history not recorded)