As exemplified previously, creating tasks is extremely simple. We provide a name and a function to grunt.registerTask and we're ready to execute. Tasks (as opposed to multitasks) are best suited to build processes that will only be performed once in a given build. A real world example of such a process might be to update a deployment log file, which we could run whenever we deploy, providing a simple history of deployments for future reference. This task might look like:

//Code example 01-deploy-log-task
var fs = require('fs'),
module.exports = function(grunt) {

  grunt.registerTask('log-deploy', function() {
    var message = 'Deployment on ' + new Date();
    fs.appendFileSync('deploy.log', message + '
'),
    grunt.log.writeln('Appended "' + message + '"'),
  });

};

On the first line, we are requiring (or importing) the built-in Node.js file system module: fs. Then, inside our log-deploy task, we'll use the fs.appendFileSync method which will append arbitrary text to a given file (first creating the file, if it doesn't exist). When we run this task, it should create a deploy.log file and display:

$ grunt log-deploy
Running "log-deploy" task
Appended "Deployment on Wed Aug 28 2013 20:43:54 GMT+1000 (EST)"

Done, without errors.

//Code example 02-task-object
module.exports = function(grunt) {

  grunt.registerTask('foo', function() {
    console.log('My task "%s" has arguments %j',
                this.name, this.args);
  });

};

$ grunt foo:bar:bazz
Running "foo:bar:bazz" (foo) task
My task "foo" has arguments ["bar","bazz"]

Done, without errors.

//Code example 03-task-aliasing
module.exports = function(grunt) {

  grunt.registerTask('build', function() {
    console.log('building...'),
  });
  grunt.registerTask('test', function() {
    console.log('testing...'),
  });

  grunt.registerTask('upload', function() {
    console.log('uploading...'),
  });

  grunt.registerTask('deploy', ['build', 'test', 'upload']);
};

$ grunt deploy
Running "build" task
building...

Running "test" task
testing...

Running "upload" task
uploading...

Done, without errors.

As with many build tools, the majority of Grunt tasks perform static checks or transforms on groups of files. This was the impetus for the introduction of multitasks. As we have seen in previous chapters, multitasks are like tasks, however, they accept multiple configurations. Grunt will use each property (except options) of a multi task's configuration as an individual configuration, called a target. This allows us to define a single task which is capable of being run many times, each time performing different actions based on each configuration. For example, let's review how we would implement a copy multitask, which copies files based on a set of one-to-one (source to destination) mappings:

//Code example 04-copy-multi-task
grunt.registerMultiTask('copy', function() {

  this.files.forEach(function(file) {
    grunt.file.copy(file.src, file.dest);
  });

  grunt.log.writeln('Copied ' + this.files.length + ' files'),
});

This task iterates through the this.files array copying each file object's source (src) to its destination (dest). In order to run this task, we must define at least one target. So, let's initialize our copy task configuration with two targets, each with two simple file mappings:

//Code example 04-copy-multi-task
grunt.initConfig({
  copy: {
    target1: {
      files: {
        'dest/file1.txt': 'src/file1.txt',
        'dest/file2.txt': 'src/file2.txt'
      }
    },
    target2: {
      files: {
        'dest/file3.txt': 'src/file3.txt',
        'dest/file4.txt': 'src/file4.txt'
      }
    }
  }
});

We can now run target2 of the copy task using the command grunt copy:target2, which should result in:

$ grunt copy:target2
Running "copy:target2" (copy) task
Copied 2 files

Done, without errors.

Furthermore, if we omit the target name and simply use the command, grunt copy, then Grunt will run all targets of the copy task:

$ grunt copy
Running "copy:target1" (copy) task
Copied 2 files

Running "copy:target2" (copy) task
Copied 2 files

Done, without errors.

Remember, the this.files array is filled with file objects using the methods described in the Configuring Files section in Chapter 2, Setting Up Grunt. This brings us to the next section on the multitask object.

Synchronous tasks are considered complete as soon as the task function returns. However, in some cases we may need to utilize libraries with asynchronous APIs. These APIs will have functions that provide their results via callbacks instead of the return statement. If we were to use an asynchronous API in a synchronous task, this would cause Grunt report success (no errors detected) and incorrectly continue onto the next task in the list.

As described previously, both the task object and the multitask object contain an async function, which notifies Grunt that the current task is asynchronous and also returns a done function. This done function is used to manually control the result of our task. For example, we could create a task that retrieves a file using HTTP and stores the contents on disk:

//Code example 05-async-webget
var request = require('request'),
var url = 'https://raw.github.com/jpillora/'+
          'gswg-examples/master/README.md';

module.exports = function(grunt) {
  grunt.registerTask('webget', function() {
    var done = this.async();
    request(url, function(err, response, contents) {
      if(err) {
        done(err);
      } else if(response.statusCode !== 200) {
        done(new Error('Not OK'));
      } else {
        grunt.file.write('FILE.md', contents);
        grunt.log.ok('FILE.md successfully created'),
        done();
      }
    });
  });
};

At the top of our example Gruntfile.js, we are requiring the popular module for performing HTTP requests: request. Since request performs an asynchronous HTTP request, we'll use the task object's async function (this.async()) to both place this task in asynchronous mode, and then retrieve the done function. Subsequently, we can signal failure to Grunt by passing an Error object or false to the done function. Anything else will signal success.

In this example, once we've received the response we shall first check that there were no errors with sending the request. If there are errors, we'll pass the err object straight to done. Next, we'll check if we received response successfully by confirming that the HTTP statusCode is 200. If it is not, we will pass our own custom error "Not OK" to done. Once both error checks have passed, we can finally write the response's contents to disk and then call done(), informing Grunt that this asynchronous task has completed successfully. So, when we run this task, we should see:

$ grunt webget
Running "webget" task
>> FILE.md successfully created

Done, without errors.