LiveReload: xrefresh for Safari & Chrome

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

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

Watch an awesome screencast by Gregg Pollack at envylabs.com.

Warning: Windows is not supported yet. We now have Windows installation instructions, but the directory watching does not work. Will be fixed later this week with transition to another monitoring API.

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

What's new?

Want to know about latest developments and smart tricks? Follow @livereload on Twitter!

Feel like chatting? Join us at [email protected] — just add this contact to your Jabber / Google Talk. (Please don't overuse this chat feature, we're trying to get some work done too!)

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.

Installing in Safari

1. You need Ruby installed. Mac OS X users already have it, Windows users get it from ruby-lang.org.

2. Install the command-line tool. On OS X and Linux:

    sudo gem update --system
    sudo gem install livereload
   

   on Windows:

    gem update --system
    gem install eventmachine --platform=win32
    gem install livereload
   

   (warning: Windows is not supported yet, see the warning in the beginning)

3. If you haven't already, you need to enable Safari extensions.

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

Installing in Chrome

1. You need Ruby installed. Mac OS X users already have it, Windows users get it from ruby-lang.org.

2. Install the command-line tool. On OS X and Linux:

    sudo gem update --system
    sudo gem install livereload
   

   on Windows:

    gem update --system
    gem install eventmachine --platform=win32
    gem install livereload
   

   (warning: Windows is not supported yet, see the warning in the beginning)

3. Visit the LiveReload page on Chrome Extension Gallery and click Install. Confirm the installation:

Done. Now you have an additional button on your toolbar:

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

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.

Known Issues (please read!)

The command-line tool uses a lame per-file watching API from EventMachine and runs out of open file limit on large projects. In Chrome, this looks like a broken connection immediately after you connect. In Safari, this looks like a crash (since Safari crashes if websocket is disconnected during handshake).

Until this is fixed, you may want to increase your ulimit -n:

ulimit -n 4096
livereload

Does not work on Windows (yet!)

Limitations

Note that you can only have one page monitored, so if you enable LiveReload on another page, the first one will stop reloading.

LiveReload does not work with local files in Chrome (since accessing file:// URLs from an extension requires an approval from the Google Chrome team) and in Safari (since we haven't bothered fixing it yet).

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.