Reloading magic with Grunt and livereload

— An article about: - Uncategorized

Think about how many times you hit F5 to refresh your page when you develop a web application. Quite a lot, I guess, not to mention the number of time you do it a second time because you weren’t sure if you had done it in the first place. It doesn’t seem much, but this ‘edit, switch to browser, F5’ routine kinda becomes a hassle at some point.

Obviously, we can’t skip the edit step. Nor can we automate when to switch to the browser. But we can definitely skip this last ‘F5’ step: using Grunt and a few plugins, we can make the browser automatically reload when we save files! Let’s see how to do it 🙂

Update – Jul 24th, 2013 : The grunt-contrib-livereload task used in this article has become deprecated. I’ve published an updated walkthrough using more recent tools.

The toolbox

First of all, let’s have a look at the tools we’ll need. Grunt is based on NodeJS and we’ll load its plugins using NPM so you’ll want to install these two. I’ll leave it to NodeJS documentation to explain you how 😉

And of course, you’ll need Grunt which is dead easy to install once you have NPM (you might need to sudo the command if you’re on a Unix platform): npm install -g grunt-cli

Project setup

For this example, we’re just going to make changes to a simple index.html file, so we’ll need a new folder with, well…, and index.html file in it. I’ll leave it’s content up to you 🙂 Just make sure it contains a little something in its <body>.

To keep everything tidy we’ll also need a package.json file to list the Grunt plugins we’ll use. They are:

  • grunt-contrib-connect, to serve the files of our project
  • grunt-regarde, to monitor the file changes
  • grunt-contrib-livereload, to reload the page in the browser

Which gives us the following package.json file (matchdep will help loading the grunt plugins in the Gruntfile):

All’s left is to install those plugin using npm install in the folder of the project. This should create a new node_modules directory in the project folder, with plenty of Grunt power inside.

It’s now time to edit the Grunt configuration to make some magic happen :).

Serving the files of the project

First thing, we’ll make Grunt start a small server so we can access our project over HTTP rather than the filesystem. Livereload uses a bit of javascript to refresh the page and having this server ready will help with injecting the Javascript code in our pages.

This is the role of the grunt-contrib-connect plugin. This makes our initial Grunt configuration (to store in a file named Grunfile.js at the root of your project):

Now if you type grunt server in your command line (from the directory of the project) and open your browser to https://localhost:9000, you’ll access the index.html page.

If opening your browser is too much of a hassle (it is for me ;)), you can even use the grunt-open plugin to make the server task open your browser for you at the right URL. Let’s add it to the package.json ("grunt-open": "~0.2.0"), install it with npm install and use it in our Gruntfile:

Boom! grunt server now starts the server and opens the browser. That’s a good start!

Setting up livereload

Next, we’re going to set up livereload, which means to things:

  • have the connect plugin insert a little piece of Javascript in the pages it serves so the browser gets notified when it needs to reload
  • start the livereload server when we serve our project and configure the port it runs on

If you have a look at your page after you use grunt server again (don’t forget to kill the one your started previously), you’ll notice two new <script> tags at the bottom of the <body>. Livereload is ready!

Reloading when the file changes

Now we have livereload ready to refresh our page, all that’s left is to configure the regarde task to trigger it when file changes:

We’re now all set up! Start the grunt server task, edit the index.html file and you’ll see you’re browser refreshing automatically, magic! (well, we all know magic is just about good tricks :)).

It also work wonders to serve the page running your QUnit/Mocha/whatever tests. Automatic testing every time you change your code! Note that you could also use grunt plugins to run your tests, but I prefer having the browser’s developer tools at hand when developing.

Pretty handy plugin, this livereload thing, don’t you think?