LiveReload

LiveReload is a Safari/Chrome extension + a command-line tool that:

Applies CSS and JavaScript file changes without reloading a page.
Automatically reloads a page when any other file changes (html, image, server-side script, etc).

Screencast by Gregg Pollack at envylabs.com.

Email support: support@livereload.com

What's new?

We are working on LiveReload 2.0 that is a native Mac app (Windows some time later too), doesn't require installing any Ruby gems and supports automatic compilation of CoffeeScript, HAML, SASS, LESS, Stylus and Jade. It will be a paid update and will be distributed via the Mac App Store. Alpha version is available at http://livereload.com (beware! it's really just an alpha!)

Version 1.x will remain available and free.

We are also now providing email support for both paid (2.0 alpha) and free (1.x) versions of LiveReload. Say hi by emailing support@livereload.com.

1.6: Configurable host & port, no-extension pure-html/js cross-browser version (see example/xbrowser.html, more docs coming soon), many small bug fixes.

1.5: Support for file:// URLs in Chrome (does not seem possible in Safari, sorry). JS live reloading is now off by default. Minor UI improvements.

1.4: Works on Windows. Sane file system monitoring (had to write it from scratch, see em-dir-watcher gem). Port number changed to 35729 because of a conflict with Zend Server. Added grace period to combine the changes made in rapid succession. Works with Vim.

1.3: Configuration file (.livereload) — you can customize extensions, configure exclusions, disable no-reload refreshing. Monitoring of multiple folders. Some bugs fixed.

1.2.2: add .erb to the list of monitored extensions (this is a gem-only update, run gem update livereload to install).

1.2.1: added workaround for Chrome bug (unable to open WebSocket to localhost), fixed problem with command-line tool trying to use kqueue on Linux.

1.2: added Chrome extension, added icon artwork, added a check that the command-line tool version is compatible with the extension version, fixed a bug with multiple stylesheet updates happening too fast.

1.1: enabled autoupdating for the Safari extension.

1.0: original release -- Safari extension and a command-line tool in a Ruby gem.

Installation

LiveReload consists of command-line monitoring tool (livereload ruby gem) and browser extensions (for Google Chrome and Safari).

Monitoring tool

Windows

Install Ruby from rubyinstaller.org/downloads. LiveReload has been tested on Ruby 1.9.1 and 1.8.7.
Download Ruby Development Kit from the same page and follow instructions.
gem install eventmachine-win32 win32-changenotify win32-event livereload --platform=ruby

Mac OS X

Mac OS X ships with Ruby installed.
You need Xcode tools installed to compile eventmachine gem. Get it from developer.apple.com.
Install RubyCocoa. If you are using rvm, you can try these instructions.
sudo gem install livereload

Linux

sudo gem install rb-inotify livereload

Another option is to use Guard with guard-livereload. It does not require RubyCocoa on Mac OS X.

Google Chrome extension

Click “Install”. Actually, LiveReload does not access your browser history. The warning is misleading.

Safari extension

Download LiveReload 1.6.2 extension. Double-click it and confirm installation:

Firefox 4 extension

Usage

Run the server in the directory you want to watch:

% livereload

You should see something like this:

Now, if you are using Safari, right-click the page you want to be livereload'ed and choose “Enable LiveReload”:

If you are using Chrome, just click the toolbar button (it will turn green to indicate that LiveReload is active).

Advanced Usage

If you want to monitor several directories, pass them on the command line:

% livereload /some/dir /another/dir /one/more/dir

(in this case it does not matter which directory you run livereload from)

Run livereload --help for a list of command-line options (there's nothing interesting there, though).

Looking to also process CoffeeScript, SASS, LessCSS or HAML? Here's a Rakefile that does that live too. (Please read the comments if you're using HAML for templates in a Rails app.)

Configuration

To:

exclude some directories or files from monitoring
monitor additional extensions (like .haml, if you're serving HAML directly from Rails without generating .html on disk)
reload the whole page when .js changes instead of applying the changes live

...you need to edit .livereload file in the monitored folder. (This file is automatically created if it does not exist when you run livereload.)

Syntax is like this:

# Lines starting with pound sign (#) are ignored.

# additional extensions to monitor
config.exts << 'haml'

# exclude files with NAMES matching this mask
config.exclusions << '~*'
# exclude files with PATHS matching this mask (if the mask contains a slash)
config.exclusions << '/excluded_dir/*'
# exclude files with PATHS matching this REGEXP
config.exclusions << /somedir.*(ab){2,4}.(css|js)$/

# reload the whole page when .js changes
config.apply_js_live = false
# reload the whole page when .css changes
config.apply_css_live = false

# wait 50ms for more changes before reloading a page
#config.grace_period = 0.05

Configuration changes are applied live (it is called Live Reload after all, that has to mean something).

A global config file (~/.livereload) is also supported if you happen to need one. It is merged with per-folder configurations.

Limitations

LiveReload does not work with local files in Safari.

Spread the word

@livereload on Twitter!

###What do our users say?

“I think LiveReload is going to change the way I work...” @mheerema

“spent a day using livereload. really impressed, very nice to watch pages update as I add / change code.” @pollingj

“Gem of the month (quarter?): LiveReload” @grimen

Feel like chatting? Join us at livereload@jaconda.im — just add this contact to your Jabber / Google Talk.

License

This software is distributed under the MIT license.

Thanks

LiveReload has been greatly inspired by (and actually borrows a few lines of code from) XRefresh, a similar tool for Firefox.

ranska/livereload