Home

Awesome

node-livereload

Build status

An implementation of the LiveReload server in Node.js. It's an alternative to the graphical http://livereload.com/ application, which monitors files for changes and reloads your web browser.

Usage

You can use this by using the official browser extension or by adding JavaScript code to your page.

Method 1: Use Browser Extension

Install the LiveReload browser plugins by visiting http://help.livereload.com/kb/general-use/browser-extensions.

Note: Only Google Chrome supports viewing file:/// URLS, and you have to specifically enable it. If you are using other browsers and want to use file:/// URLs, add the JS code to the page as shown in the next section.

Once you have the plugin installed, start livereload. Then, in the browser, click the LiveReload icon to connect the browser to the server.

Method 2: Add code to page

Add this code:

<script>
  document.write('<script src="http://' + (location.host || 'localhost').split(':')[0] +
  ':35729/livereload.js?snipver=1"></' + 'script>')
</script>

Note: If you are using a different port other than 35729 you will need to change the above script.

Running LiveReload

You can run LiveReload two ways: using the CLI application or by writing your own server using the API.

Method 1: Using the Command line Interface

To use livereload from the command line:

$ npm install -g livereload
$ livereload [path] [options]

To watch files in the current directory for changes and use the default extensions, run this command:

$ livereload

To watch files in another directory, specify its path:

$ livereload ~/website

The commandline options are

For example, to use a wait time and turn on debugging so you can see messages in your terminal, execute livereload like this:

$ livereload -w 1000 -d

To turn on debugging and tell Livereload to only look at HTML files in the public directory, run it like this:

$ livereload public/ -e 'html'

The file path can be at any place in the arguments. For example, you can put it at the end if you wish:

$ livereload -e 'html' public/

Finally, you can tell LiveReload to refresh the browser when specific filenames change. This is useful when there are files that don't have extensions, or when you want to exclude all HTML files except for index.html throughout the project. Use the -f or --filesToReload option:

$ livereload -f 'index.html' public/

All changes to index.html in any subdirectory will cause LiveReload to send the reload message.

Option 2: From within your own project

To use the api within a project:

$ npm install livereload --save

Then, create a server and fire it up.

var livereload = require('livereload');
var server = livereload.createServer();
server.watch(__dirname + "/public");

You can also use this with a Connect server. Here's an example of a simple server using connect and a few other modules just to give you an idea:

var connect  = require('connect');
var compiler = require('connect-compiler');
var static = require('serve-static');

var server = connect();

server.use(
  compiler({
      enabled : [ 'coffee', 'uglify' ],
      src     : 'src',
      dest    : 'public'
  })
);

server.use(  static(__dirname + '/public'));

server.listen(3000);

var livereload = require('livereload');
var lrserver = livereload.createServer();
lrserver.watch(__dirname + "/public");

You can then start up the server which will listen on port 3000.

Server API

The createServer() method accepts two arguments.

The first are some configuration options, passed as a JavaScript object:

The second argument is an optional callback that will be sent to the LiveReload server and called for the listening event. (ie: when the server is ready to start accepting connections)

Watching multiple paths:

Passing an array of paths or glob patterns will allow you to watch multiple directories. All directories have the same configuration options.

server.watch([__dirname + "/js", __dirname + "/css"]);

Command line:

$ livereload "path1, path2, path3"

Using the originalPath option

You can map local CSS files to a remote URL. If your HTML file specifies live CSS files at example.com like this:

<!-- html -->
<head>
  <link rel="stylesheet" href="http://domain.com/css/style.css">
</head>

Then you can tell livereload to substitute a local CSS file instead:

// server.js
var server = livereload.createServer({
    originalPath: "http://domain.com"
});
server.watch('/User/Workspace/test');

Then run the server:

$ node server.js

When /User/Workspace/test/css/style.css is modified, the stylesheet will be reloaded on the page.

Troubleshooting

The browser extension doesn't connect.

If you're using file:/// urls, make sure the browser extension is configured to access local files. Alternatively, embed the livereload.js script on your page as shown in this README.

When I change the HTML page I'm working on, the browser refreshes and tells me the file isn't found.

Your editor is most likely using a swapfile, and when you save, there's a split second where the existing file is deleted from the file system before the swap file is saved in its place. This happens with Vim. You can disable swapfiles in your editor, or you can add a slight delay to Livereload using the -w option on the command line.

Developing livereload

This library is implemented in CoffeeScript 1.x. It may eventually be converted to JavaScript, but because there are many projects that depend on this library, the conversion isn't a priority.

To build the distributable versions, run npm run build.

Run npm test to run the test suite.

Contributing

Contributions welcome, but remember that this library is meant to be small and serve its intended purpose only. Before submitting a pull request, open a new issue to discuss your feature or bug. Please check all open and closed issues.

When submitting code, please keep commits small, and do not modify the README file. Commit both the Coffee and JS files.

Changelog

0.9.3

0.9.2

0.9.1

0.9.0

0.8.2

0.8.1

0.8.0

0.7.0

0.6.3

0.6.2

0.6.1

0.6.0

0.5.0

0.4.1

0.4.0

Older version history not kept.

License

Copyright (c) 2010-2021 Brian P. Hogan and Joshua Peek

Released under the MIT license. See LICENSE for details.