Grunt Cookbook

Assuming that you already have a global installation of Node.js, the following is the command to install the Grunt CLI:

$ npm install --global grunt-cli

If the installation was successful, the grunt command should now be available on the terminal. Test this by typing grunt in your terminal and confirm that it returns a message similar to the following:

grunt-cli: The grunt command line interface. (v0.1.13)

Fatal error: Unable to find local grunt.

If you're seeing this message, either a Gruntfile wasn't found or grunt hasn't been installed locally to your project. For more information about installing and configuring grunt, please see the Getting Started guide:

http://gruntjs.com/getting-started

First, we'll install the Grunt libraries in the current project path, and have it added to our project dependencies. This can all be done by using the following command:

$ npm install --save grunt

Next, we'll set up an empty configuration file that would, at the very least, allow Grunt to run and also provides a place for future task configurations. Let's create a file called Gruntfile.js in the root directory of our project with the following contents:

module.exports = function (grunt) {
  grunt.initConfig({});
  grunt.registerTask('default', []);
};

Now that we have the Grunt libraries installed and a basic configuration file set up, we can use the grunt command to test that it's all working as expected. Running the grunt command in the terminal should now produce output similar to the following:

Done, without errors.

The first step of installing a plugin is to install the package that contains it in the current project path. For our example, we'll install the contrib-jshint plugin that is contained in the grunt-contrib-jshint package. We can install this package and add it to our project dependencies by using the following command:

$ npm install --save grunt-contrib-jshint

Next, we'll have to load the tasks contained in the plugin package so they can be used in our configuration. This is done using the loadNpmTasks function, provided to us by the grunt object that is passed to us in the configuration file. After adding this, our configuration file should look similar to the following:

module.exports = function (grunt) {
  grunt.initConfig({});
  grunt.loadNpmTasks('grunt-contrib-jshint');
  grunt.registerTask('default', []);
};

Now that we have the package installed and its tasks loaded, we can use the loaded tasks in our configuration. For our example, we had the jshint task loaded, which enables us to use it in a manner similar to the following:

module.exports = function (grunt) {
  grunt.initConfig({
    jshint: {
      sample: {
        files: 'src/*.js'
      }
    }
  });
  grunt.loadNpmTasks('grunt-contrib-jshint');
  grunt.registerTask('default', []);
};

Install the utility's package in the current project path and add it to your dependencies by using the following command:

$ npm install --save load-grunt-tasks

Now we can use it in our configuration file by importing the package and passing the grunt object to it. Now that we're making use of this utility, we can also remove all the loadNpmTasks we were using to load our plugins. This should result in a configuration file similar to the following:

module.exports = function (grunt) {
  require('load-grunt-tasks')(grunt);
  grunt.initConfig({
    jshint: {
      sample: {
        files: 'src/*.js'
      }
    }
  });
  grunt.registerTask('default', []);
};

We'll start by installing the package containing the contrib-connect plugin and loading its tasks as given in the instructions provided in the Installing a plugin recipe of this chapter.

With the connect task loaded from the plugin, we can make use of it in our configuration. To do this, we add the following to our configuration:

connect: {
  server: {
    options: {
      base: 'www',
      keepalive: true
    }
  }
}

Let's add a simple file that we'd like to have served from our server so that we have something to test it with. Create a directory called www in the project root, and then a file inside it called index.html, with the following contents:

<html>
  <head>
    <title>Test Page</title>
  </head>
  <body>
    <h1>This is a test page.</h1>
  </body>
</html>

Now we can run our web server using the grunt connect command, which will produce output indicating that our server started, along with a URL of where it can be reached:

Running "connect:server" (connect) task
Waiting forever...
Started connect web server on http://0.0.0.0:8000

Finally, we can use our favorite browser to pay a visit to the URL mentioned in the output. This would show us our example page, as served through our running server:

We'll start by installing the package that contains the contrib-watch plugin and loading its tasks by following the instructions provided in the Installing a Plugin recipe of this chapter.

For our example, we'll make use of the jshint task to analyze the quality of a JavaScript source file. Let's install the contrib-jshint plugin and load its tasks by following the instructions provided in the Installing a Plugin recipe of this chapter.

We'll also need a JavaScript source file that we can watch for changes and perform a quality analysis on. Let's create a file called sample.js in our project root and provide it with the following contents:

var sample = 'Sample';
console.log(sample);

Now, we can set up the example jshint task, which we'll run using the watch task by adding the following to our configuration:

jshint: {
  sample: {
    src: ['sample.js']
  }
}

With the plugin installed and the sample task configured, we can now configure a target on the watch task, which will run the jshint task every time the sample file called sample.js changes. This is done by adding the following to our configuration:

watch: {
  sample: {
    files: ['sample.js'],
    tasks: ['jshint']
  }
}

Finally, we can start the task using the grunt watch command, which should produce the following output to confirm that it's running:

Running "watch" task
Waiting...

To test our setup, we can now make some changes to the sample.js file and save them. This should produce output informing us of the file event similar to the following:

Running "watch" task
Waiting...
>> File "sample.js" changed.
Running "jshint:sample" (jshint) task
>> 1 file lint free.

Done, without errors.
Completed in 1.0s at Wed Jan 1 2014 00:00:00 GMT - Waiting...

We'll start by installing the packages containing the contrib-connect and contrib-watch plugins and loading their tasks by following the instructions provided in the Installing a plugin recipe of this chapter.

For the sake of our example, we'll create a file called index.html in the www directory, which will be the file that we wish to view in a browser and have automatically updated when changes are made to it. The contents for this file follows:

<html>
  <head>
    <title>LiveReload Test</title>
  </head>
  <body>
    <h1>First there was this.</h1>
  </body>
</html>

Next, we'll set up our development server, which will serve the index.html file from the www directory. Along with the standard configuration, we'll set the livereload option to true, indicating that the development server should enable the browser to receive LiveReload triggers. This is all done by adding the following to our configuration:

connect: {
  dev: {
    options: {
      base: 'www',
      livereload: true
    }
  }
}

Now, we'll set up a watcher to observe file events in the www/index.html file. Along with the standard configuration, we'll set the livereload option to true, indicating that the appropriate LiveReload triggers should be sent whenever changes are observed. This is done by adding the following to our configuration:

watch: {
  www: {
    files: ['www/index.html'],
    options: {
      livereload: true
    }
  }
}

Finally, we can start our server and watcher using the grunt connect watch command, which should produce output indicating the start of both:

Running "connect:dev" (connect) task
Started connect web server on http://0.0.0.0:8000

Running "watch" task
Waiting...

Now, we can use our favorite browser to open the URL mentioned in the output, which should show us our sample page as served by the server:

Let's try out the LiveReload functionality by changing the www/index.html file and saving it. This action should produce the following output in the terminal in which the server and watcher were started:

>> File "www/index.html" changed.
Completed in 0.001s at Wed Jan 01 2014 00:00:00 GMT – Waiting...

Switching back to our browser that currently has the http://0.0.0.0:8000 URL open, we should now see the updated page, without having initiated a manual refresh:

We'll start by installing the package containing the newer plugin and loading its tasks by following the instructions provided in the Installing a plugin recipe of this chapter.

For the purpose of our example, we'll also install the contrib-jshint plugin and load its tasks by following the instructions provided in the Installing a plugin recipe of this chapter.

With all the required plugins installed, we can now add sample configuration for the jshint task, which will perform a code quality check on all the JavaScript files in the src directory. This is done by adding the following to our configuration:

jshint: {
  sample: {
    src: 'src/**/*.js'
  }
}

Now we can run the jshint task a couple of times using the grunt jshint command to observe its behavior. Each time we run it, we'll see that it scans all the files in the src directory. This should produce the same output each time, similar to the following:

Running "jshint:sample" (jshint) task
>> 3 files lint free.

In order to make use of the newer plugin, we prepend newer: to the name of the task we wish to run. On running the grunt newer:jshint command the first time, the newer plugin will cache the timestamps of the files that have been processed. This produces output similar to the following:

Running "newer:jshint" (newer) task

Running "newer:jshint:sample" (newer) task

Running "jshint:sample" (jshint) task
>> 3 files lint free.

Running "newer-postrun:jshint:sample:.cache" (newer-postrun) task

When we run the grunt newer:jshint command again, we'll see that no files are processed by the jshint task, which produces output similar to the following:

Running "newer:jshint" (newer) task

Running "newer:jshint:sample" (newer) task
No newer files to process.

Now, we can change one of the files in the src directory and run the command again to see that the changed file is processed again:

Running "newer:jshint" (newer) task

Running "newer:jshint:sample" (newer) task

Running "jshint:sample" (jshint) task
>> 1 file lint free.

Running "newer-postrun:jshint:sample:1:.cache" (newer-postrun) task

We'll start by installing the package that contains the contrib-watch plugin and loading its tasks by following the instructions provided in the Installing a plugin recipe of this chapter.

Now, we'll add a watch task, which will run the jshint task when it observes changes on any of the JavaScript files contained in the src directory. We'll also prepend the jshint task with newer: to indicate that we only want to process the files that actually changed. This is done by adding the following to our configuration:

watch: {
  jshint: {
    files: ['src/**/*.js'],
    tasks: ['newer:jshint']
  }
}

Now, we can start the watch task by using the grunt watch command in the terminal. This should produce output similar to the following, indicating that the watcher is running:

Running "watch" task
Waiting...

If we now change and save a file in the src directory, we should see output similar to the following, indicating that only the file that was changed has been processed by the jshint task:

>> File "src/file.js" changed.
Running "newer:jshint" (newer) task

Running "newer:jshint:sample" (newer) task

Running "jshint:sample" (jshint) task
>> 1 file lint free.

Running "newer-postrun:jshint:sample:1:.cache" (newer-postrun) task

For our example, we'll make use of the contib-uglify plugin, which can be used to compress JavaScript source files. Let's install it and load its tasks for using the instructions provided in the Installing a Plugin recipe of this chapter.

We'll also need a simple JavaScript source file for the sake of our example. Let's create a file called sample.js in the root of our project directory and fill it with the following code:

module.exports = function () {
  var sample = 'Sample';
  console.log(sample);
};

Next, we'll import the data contained in our project's pacakge.json file by making use of the grunt.file.readJSON function and assigning its result to a property called pkg in our configuration. After adding this, our configuration object should look similar to the following:

{
  pkg: grunt.file.readJSON('package.json')
}

Now that we have the data imported form our project package, we can set up an uglify task, which will compress a JavaScript source file called sample.js, using the version number contained in the package.json file as part of the resulting file's name. This is done by adding the following to our configuration:

uglify: {
  sample: {
    files: {
      'sample_<%= pkg.version %>.js': 'sample.js'
    }
  }
}

Finally, we can use the grunt uglify command to test our setup, which should produce output similar to the following:

Running "uglify:sample" (uglify) task
File sample_0.0.0.js created: 81 B → 57 B

We can now also take a look at our newly generated compressed version of the sample.js file in the sample_0.0.0.js file, which should have content similar to the following:

module.exports = function(){var a="Sample";console.log(a)};

First, we'll create a simple YAML file for the purpose of our example. Let's create sample.yaml in our project root and give it the following content:

version: 0.0.0

Now all we need to do is change the call to grunt.file.readJSON to import our sample YAML file instead. We do this by changing the pkg configuration to the following:

pkg: grunt.file.readYAML('sample.yaml')

If we now run the Grunt uglify command, we should see the same result as before, with output similar to the following:

Running "uglify:sample" (uglify) task
File sample_0.0.0.js created: 81 B → 57 B