Specifying Dependencies

Every project should have a package.json file that lists the dependencies for the script. At a minimum, this should contain the project name, the version, and a dependency on the Grunt package. At the time of writing, the current version of Grunt is 0.4.1, so that is used in the package.json code here:

{
 "name": "Beginning_Backbone",
 "version": "0.1.0",
 "devDependencies": {
   "grunt": "∼0.4.1"
 }
}

Node.js will look after installing all the dependencies for your project if you run the following from the command line, in the same directory as package.json:

npm install

This script reads the contents of package.json and installs all the packages listed in devDependencies locally. As new tasks are added to the Gruntfile, you should add an entry in the devDependencies section of this file.

Note that you can also use the --saveDev flag in the install command to have a plug-in downloaded locally and also have its name and version saved along with the other dependencies in your package.json. The following command adds the appropriate entry for the latest version of Grunt to the .json file:

npm install grunt --save-dev

This can be a useful way to both install plug-ins locally and update the dependency configuration for other developers in your team in one simple command. If using a version control system, you will typically want to exclude the node_modules folder, leaving other developers who check out your code to reinstall the modules locally.

Project Configuration

As well as providing details on the dependencies, any other project-related attributes can be stored in package.json. Usually, this file is read as a JSON object during the initialization of the Grunt script.

All of this initial configuration takes place in the grunt.initConfig function, which is also used for task configuration, as we’ll see shortly. The attributes stored in this file, especially the version, may also be useful for your build script. Grunt provides a file API to allow you to easily read the JSON into your script.

module.exports = function(grunt) {

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

};

We’re still not at a place where the Gruntfile will execute properly. If you run grunt from the command line now, you’ll be informed that you are missing a default task.

Warning: Task "default" not found. Use --force to continue.

Adding a Task

Let’s now look at how to add a default task for our build script to execute. We’ll use the same sample as at http://gruntjs.org, which uses the JavaScript uglify plug-in. The uglify plug-in provides the ability to minify (compress) all your JavaScript source into one file. Any of the scripts that you have downloaded from third parties will usually have such a version, appended with  .min.js, named as the production version.

The uglify task is available from GitHub at https://github.com/gruntjs/grunt-contrib-uglify. It provides the instructions you need to get started, but let’s go through this step-by-step.

First you will need to install the uglify task using the Node Package Manager, with the --save-dev flag.

npm install grunt-contrib-uglify --save-dev

This results in package.json being updated as follows, with the addition of uglify in the dependencies:

{
 "name": "Beginning_Backbone",
 "version": "0.1.0",
 "devDependencies": {
   "grunt": "∼0.4.1",
   "grunt-contrib-uglify": "∼0.2.4"
 }
}

Now that the task is available, it needs to be loaded in the Gruntfile. Any task contained in a node module can be loaded using the grunt.loadNpmTasks function, as in the following code snippet:

// Load the plugin that provides the "uglify" task.
grunt.loadNpmTasks('grunt-contrib-uglify'),

The next step is to set up the configuration for the uglify task. This, along with the configuration for any task, takes place in the initConfig block. There are lots of different configuration options for the uglify task, but we’ll just use the simplest.

First the uglify plug-in’s configuration object needs to be included in the initConfig, with an options property, which defines the banner (comment) to use in the minified file. All tasks allow an options property to be included to override any built-in defaults.

Note how the <%= %> tag allows configuration properties to be included in the task. In this case, pkg.name is read from package.json. Meanwhile, Grunt provides other configuration variables such a grunt.template.today to print a formatted date.

The build object contains details of the source files to use with the src property, in this case all JavaScript files stored within js/app. It also contains a dest property, which defines where the output file will go.

grunt.initConfig({
   pkg: grunt.file.readJSON('package.json'),
   uglify: {
     options: {
       banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */
'
     },
     build: {
       src: 'js/app/**/*.js',
       dest: 'build/<%= pkg.name %>.min.js'
     }
   }
 });

Every task you encounter will have different configuration objects. If you define a property that is not required, it will just be ignored by the script. You can even add complete JavaScript to the configuration, if you find that simple properties do not suffice.

The bare minimum of any Gruntfile dictates that a default task must exist. This can be added using the grunt.registerTask function, which takes the name of the task and takes an array of subtasks that will be executed as part of the task. In this case, there is just one task to include: uglify.

grunt.registerTask('default', ['uglify']);

The complete listing of the Gruntfile is now as follows:

module.exports = function(grunt) {

grunt.initConfig({
   pkg: grunt.file.readJSON('package.json'),
   uglify: {
     options: {
       banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */
'
     },
     build: {
       src: 'js/app/**/*.js',
       dest: 'build/<%= pkg.name %>.min.js'
     }
   }
 });

 // Load the plugin that provides the "uglify" task.
 grunt.loadNpmTasks('grunt-contrib-uglify'),

 // Default task(s).
 grunt.registerTask('default', ['uglify']);

};

Executing grunt on the command line will now execute the uglify task, generating a file named Beginning_Backbone.min.js in the build directory. Throughout this chapter we will continue to extend this Gruntfile to create a complete build script for continuous integration.

The Importance of Static Analysis

As JavaScript has matured over the years, most browsers have added measures that make them more lenient and make them accept “bad” code. Because JavaScript is a dynamic language, there is a high chance of unruly code that might cause problems hidden to code reviewers and inexperienced developers.  Most mature languages have static analysis tools, and with JavaScript it’s even more important, given the chance of sloppy code. By adding an automated check, you can help ensure that your code is given every chance to shine. Although sometimes the errors that static analysis uncovers may be uncomfortable to address at first, you will end up with a much cleaner code base by using a lint tool.

Installation and Configuration

To install JSHint and add the dependency to your project, run the following from the command line:

npm install grunt-contrib-jshint --save-dev

Now, in the Gruntfile we’ll need to load the node module for JSHint.

grunt.loadNpmTasks('grunt-contrib-jshint'),

The configuration of the jshint task takes place mostly in the options configuration object, which accepts a number of different lint checks to carry out. Any checks that you want to carry out should be set to true. Table 9-4 lists some of the most commonly used JSHint checks. A complete list of these checks is available at www.jshint.com/docs/options/.

The options for this task also include an ignores attribute, where you can specify a list of files to ignore. Typically, you will ignore any external libraries you have included in your project.

The initConfig section should now include a JSHint task defined similar to the following. Note that not all of the checks listed earlier have been enforced.

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

   jshint: {
     options: {
       curly: true,
       eqeqeq: true,
       eqnull: true,
       browser: false,
       globals: {
         jQuery: true
       },
       ignores: ['js/external/**/.*.js']
     },
     files: {
       src: ['js/app/**/*.js']
     },
 },
});

Finally, the task needs to be added to the default task. The registerTask function takes two parameters: the alias for the task and an array of tasks that will be executed under that alias.

grunt.registerTask('default', ['jshint']);

Some formatting errors may appear in your source such as mixed spaces and tabs. You have the choice to fix them by using a JavaScript source formatter, such as JSFormat in Sublime Text. You can also just choose to remove the check from your JSHint configuration.

After formatting the source code, you might still have some remaining errors, which will get output to the console, as in Figure 9-2. Most of the errors that JSHint throws up are pretty easy to follow, but if you have any trouble, you can find explanations at http://jslinterrors.com/.

If you are running on your local machine, printing to the console is OK. However, when running on continuous integration servers, it is more desirable to have the output go to a file. Naturally, the task has a configuration option for this eventuality, by using the reporterOutput attribute that takes a filepath as its parameter.

jshint: {
  options: {
    curly: true,
    eqeqeq: true,
    eqnull: true,
    browser: false,
    globals: {
      jQuery: true
    },
    ignores: ['js/external/**/.*.js'],
    reporterOutput : 'reports/jshint.txt'
  },
  files: {
    src: ['js/app/**/*.js']
  },

The previous code snippet shows how the report of the JSHint run will now be written to a jshint.txt file in the reports directory.

The Importance of Code Compression

While running your JavaScript code on your development machine, your focus is on getting everything working. There’s nothing wrong with this, but when your code goes into production, you will need to take performance into consideration. Running tools such as YSlow (http://developer.yahoo.com/yslow/) will analyze your web app for any performance issues and give you suggestions on how to fix these issues.

One of the most common problems is the inclusion of too many external JavaScript scripts. Each of the HTTP requests required to load one of these scripts takes time. As well as the network overhead, uncompressed JavaScript will also mean more data is being transferred. By minifying your JavaScript, you ensure that you are avoiding one of the most common performance issues in web apps.

Installation and Configuration

To install uglify and add the dependency to your project, run the following from the command line:

npm install grunt-contrib-uglify --save-dev

Now, in the Gruntfile we’ll need to load the node module for uglify:

grunt.loadNpmTasks('grunt-contrib-uglify'),

Table 9-5 lists some of the options available when configuring the uglify task.

To ensure your minification is successful, you will first need to consider the order in which the uncompressed scripts are loaded. In our app example, all the external scripts were loaded first, in a particular order, before we loaded our own Backbone code.

While you can choose to use minified versions of the external libraries, we’ll include them in a separate minified file. This results in the number of scripts loaded going from 18, as in the following code snippet, to 2.

<!-- General Includes -->
<script src="js/external/jquery-1.10.2.js"></script>
<script src="js/external/underscore.js"></script>
<script src="js/external/backbone.js"></script>
<script src="js/external/handlebars.js"></script>
<script src="js/external/moment.js"></script>
<script src="js/external/dialog.js"></script>

<!-- Model -->
<script src="js/app/model/Tweet.js"></script>
<script src="js/app/model/Profile.js"></script>
<script src="js/app/model/Search.js"></script>
<!-- Collections -->
<script src="js/app/collection/Timeline.js"></script>
<!-- View -->
<script src="js/app/view/TimelineView.js"></script>
<script src="js/app/view/ProfileView.js"></script>
<script src="js/app/view/ProfilePopupView.js"></script>
<script src="js/app/view/SearchView.js"></script>
<script src="js/app/view/ResultsView.js"></script>
<!-- Router -->
<script src="js/app/router/AppRouter.js"></script>
<!-- Util -->
<script src="js/app/util/Helpers.js"></script>
<!-- The 'main' for this app -->
<script src="js/app/app.js"></script>

As we can create subtasks within any of our tasks, we’ll split uglify into two: one for external scripts and one for our own JavaScript source.

uglify: {
     options: {
       banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */
'
     },
     externalLibraries: {
        //WILL DEAL WITH EXTERNAL
         },
     individuals: {
        //WILL DEAL WITH OUR SOURCE
         }
   }

The file listing to be used for the externalLibraries section should be explicit to ensure that the source files are minified in the order that they are loaded. All of these files are minified into external.min.js in the build directory.

externalLibraries: {
       files:{
         'build/external.min.js' : ['js/external/jquery-1.10.2.js',
                                   'js/external/underscore.js',
                                   'js/external/backbone.js',
                                   'js/external/handlebars.js',
                                   'js/external/moment.js',
                                   'js/external/dialog.js']
       }
     },

The minification task for our own source code can be slightly different. There are no interdependencies between the files that exist in the same subdirectory. For example, no model object depends on another. Therefore, we can using the ** pattern to include all the files, one subdirectory at a time.

app: {
       files : {
         'build/app.min.js'       : ['js/app/model/*.js', 'js/app/collection/*.js',
                                     'js/app/view/*.js', 'js/app/router/*.js',
                                     'js/app/util/.*.js', 'js/app/*.js' ],
       }
     }

Now the uglify task needs to be included to the list of default tasks.

grunt.registerTask('default', ['jshint','uglify' ]);

Once run, you can change the index.html file of your app to use the minified files. The following should be the only script includes required by the application:

<script src="build/external.min.js"></script>
<script src="build/app.min.js"></script>
 

As you try your application with the minified scripts, you may find some JavaScript errors happen during loading. Ensure that you have included all the required files in the correct order if this happens.

For reference, the complete code listing for the uglify task should look as follows:

uglify: {
     options: {
       banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */
',
       report: 'min'
     },

     externalLibraries: {
       files:{
         'build/external.min.js' : ['js/external/jquery-1.10.2.js',
                                   'js/external/underscore.js',
                                   'js/external/backbone.js',
                                   'js/external/handlebars.js',
                                   'js/external/moment.js',
                                   'js/external/dialog.js']
       }
     },
     app: {
       files : {
         'build/app.min.js'       : ['js/app/model/*.js', 'js/app/collection/*.js',
                                     'js/app/view/*.js', 'js/app/router/*.js',
                                     'js/app/util/.*.js', 'js/app/*.js' ],
       }
     }
   }

Note the addition of the report property in the options of the task. This results in the minification savings being printed to the console after the task executed. Figure 9-3 shows the savings made by running uglify on our source.

Installation and Configuration

To install CSSMin and add the dependency to your project, run the following from the command line:

npm install grunt-contrib-cssmin --save-dev

Now, in the Gruntfile we’ll need to load the node module.

grunt.loadNpmTasks('grunt-contrib-cssmin'),

CSSMin is a simple tool, so just a few options are available for the configuration of the task. Table 9-6 lists some of the options available when configuring the CSSMin task.

The application we have created has a limited amount of CSS included, but it’s still worth compressing in order to make the files smaller, and reduce the loading overhead. Currently index.html includes references to two style sheets.

<link rel='stylesheet' href='css/modern.css'>
<link rel="stylesheet" href="css/style.css">

The Grunt task configuration is quite simple, containing a combine object with the list of files that needs to be included to generate the app.min.css file.

cssmin:{
     combine:{
         files: {
           'build/app.min.css' : ['css/**.css']
         }
     }
}

Now the CSSMin task needs to be included in the list of default tasks.

grunt.registerTask('default', ['jshint','uglify','cssmin' ])

Following the minification process, the two CSS files can be replaced by this single minified CSS:

<link rel='stylesheet' href='css/app.min.css'>

QUnit Task

The QUnit Grunt plug-in (https://github.com/gruntjs/grunt-contrib-qunit) allows you to automate the execution of the QUnit test suite created in the previous chapter. When you download the plug-in, it will automatically download PhantomJS as a dependency. This means that the task can run in the background without a standard browser.

npm install grunt-contrib-qunit --save-dev

grunt.loadNpmTasks('grunt-contrib-qunit'),

qunit:{
     all: {
       options: {
         urls: ['http://localhost/backbone/chapter9/js/test/app.html']
       }
     }
}

grunt.registerTask('default', ['jshint', 'uglify', 'cssmin', 'qunit']);

npm install grunt-qunit-junit --save-dev

grunt.loadNpmTasks('grunt-qunit-junit'),

//qunit reports
    qunit_junit: {
           options: {
              //the location to generate reports to
              dest: 'reports/'
           }
     }
 

grunt.registerTask('default', ['jshint', 'uglify', 'cssmin', 'qunit_junit', 'qunit']);

Jasmine Task

In the previous chapter, we also explored using Jasmine to write your tests, as an alternative to QUnit. A grunt task exists to execute Jasmine tests (see https://github.com/gruntjs/grunt-contrib-jasmine). Just as with the QUnit task, Jasmine has a dependency on PhantomJS and will install it if required.

npm install grunt-contrib-jasmine --save-dev

grunt.loadNpmTasks('grunt-contrib-jasmine'),

grunt.loadNpmTasks('grunt-contrib-jasmine'),

 //jasmine tests
 jasmine: {
   main: {
   src: ['js/app/model/Profile.js', 'js/app/model/Tweet.js', 'js/app/collection/Timeline.js'],

   options: {
        specs: 'js/test/jasmine/spec/ProfileSpec.js',
        vendor : ['js/test/sinon.js', 'build/external.min.js', 'js/test/jasmine/lib/jasmine-jquery.js'],
        junit :{
         path: 'reports/'
        }
       }
     }
 }

grunt.registerTask('default', ['jshint', 'uglify', 'cssmin', 'qunit_junit', 'qunit', 'jasmine']);