A front-end build with Grunt 0.4

Update February 22, 2013:
Grunt 0.4 is officially released. Please take that into account when following the instructions below.

Addy Osmani’s talk on the developer toolbelt at Fronteers 2012 inspired me to have a closer look at Grunt. Especially for front-end or JavaScript driven projects, Grunt looks like a promising alternative to the Ant or Maven build systems.

Note: this is not a tutorial on Grunt or build systems in general. If you’re new to building read the Grunt introduction on Nettuts. This article aims to overcome the pitfalls when setting up a build with Grunt 0.4. Grunt version 0.4 differs a lot from 0.3, but unfortunately both the Grunt documentation as well as a lot of plugin documentation have shortcomings regarding which Grunt version is supported.

Prerequisites

If you want to follow the coming steps, the following tools should be installed on your system:

• Node.js (version 0.8.0 or higher)
• PhantomJS (in this example only needed for Jasmine testing)

Preface – why Grunt 0.4?

The current stable release of Grunt is version 0.3.2 and you can find some useful tutorials on it. However, when I tried to implement it, I discovered that some useful Grunt plugins only worked in Grunt 0.4. Unfortunately, compatibility between Grunt 0.3 plugins and Grunt 0.4 plugins is a big issue. So in the end I chose to end my sufferings on Grunt 0.3 and to use Grunt 0.4 instead.

Grunt 0.4 should be feature complete but is not yet released because of plugin incompatibility issues. On the web you can find a lot of Grunt plugins of which it’s not directly clear which version of Grunt they support. Fortunately, all plugins that are prefixed with grunt-contrib- support Grunt 0.4. More details can be found in the article Upgrading from 0.3 to 0.4. Another clou that a plugin is 0.4-proof is the use of “Gruntfile.js” in examples. In 0.3 this file was named “grunt.js”.

Installing Grunt’s Command Line Interface

Starting with version 0.4 it’s no longer recommended to install Grunt globally on your system. Instead, each project holds it’s own Grunt version and hence the Grunt plugins that support that version.

To be able to run Grunt globally you just need to install the command line interface, which can be installed as a Node.js module with the following command:

npm install -g grunt-cli

Check grunt-cli github’s page for more information.

Installing Grunt 0.4

First, in the root of your project, create a file named package.json with these minimal contents:

{
  "name": "my-project",
  "version": "0.1.0"
}

In the terminal, also in the root of your project, run:

npm install grunt@0.4.0a --save-dev

Note: Once Grunt 0.4 is released, it should be sufficient to run just:

npm install grunt --save-dev

The –save-dev options saves the installed version in the project’s package.json. It’s recommended to add this parameter too when installing Grunt plugins.

Next, create a file named Gruntfile.js with at least the following contents:

module.exports = function(grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json')
  });
};

Now we’ve completed the minimal Grunt setup and we’re able to run the Grunt build command:

grunt

In our case, it’s leads to an error because we didn’t define any tasks yet: “Warning: Task “default” not found. Use –force to continue.” We need to install at least one grunt plugin to get it rolling.

Installing Grunt plugins

Starting with version 0.4 Grunt is no longer shipped with default tasks. We will have to install all tasks ourselves. Hundreds of grunt tasks are available to suit your needs. In my project I’ve so far chosen the following tasks, in alphabetical order:

• Build – to replace file names in static or generated sources.
• Clean – to clean up the build directory.
• Copy – to copy static files to the build directory.
• FTP-deploy – to automatically deploy the build directory to my web server.
• Jasmine – to unit test JavaScript.
• JsHint – to lint test JavaScript.
• Uglify – to minimize and concatenate JavaScript files.
• Sass – to generate CSS from SASS-files and to minimize and concatenate them.

All plugins can be easily installed from command line:

npm install grunt-contrib-build --save-dev
npm install grunt-contrib-clean --save-dev
npm install grunt-contrib-copy --save-dev
npm install grunt-contrib-jasmine --save-dev
npm install grunt-contrib-jshint --save-dev
npm install grunt-contrib-sass --save-dev
npm install grunt-contrib-uglify --save-dev
npm install grunt-ftp-deploy --save-dev

Plugin configuration is done in Gruntfile.js. Take a look a this example for inspiration.

Finding grunt plugins

Finally, finding grunt plugins can be done via Google, the Grunt homepage, but also command line:

npm find gruntplugin <search term>

Happy grunting!