Matt Bailey
Designer & Developer

Jump To Content

A beginner's guide to Grunt

image

UPDATE 22 November, 2014: I've just published a brand new article on how I now set up and use Grunt. Check it out.

Having just read David Bushell’s article on [frontend] automation¬†I thought I’d have a go at installing Grunt myself and setting up a project. However, I found the process and documentation on the Grunt website a bit ‘meandering’. In an effort to keep a record for myself, and to help others, I thought I’d write a simple step by step guide.

All the Grunt documentation can be found here: http://gruntjs.com/getting-started

At the time of writing the node.js and Grunt versions are as follows:

node.js - v0.10.0
grunt-cli - v0.1.6
grunt - v0.4.1

1. Install node.js

Download and follow the install instructions for node.js here: http://nodejs.org/

2. Install grunt-cli

grunt-cli docs: http://gruntjs.com/getting-started

Install grunt-cli (the Grunt command line interface):

npm install -g grunt-cli

This puts the grunt command in your system path, allowing it to be run from anywhere.

3. Install grunt-init

grunt-init docs: http://gruntjs.com/project-scaffolding

grunt-init is a scaffolding tool used to automate project creation.

Install grunt-init:

npm install -g grunt-init

4. Install some grunt-init templates

Install some grunt-init templates to help get you started. For example:

git clone git@github.com:gruntjs/grunt-init-commonjs.git ~/.grunt-init/commonjs
git clone git@github.com:gruntjs/grunt-init-gruntfile.git ~/.grunt-init/gruntfile
git clone git@github.com:gruntjs/grunt-init-gruntplugin.git ~/.grunt-init/gruntplugin
git clone git@github.com:gruntjs/grunt-init-jquery.git ~/.grunt-init/jquery
git clone git@github.com:gruntjs/grunt-init-node.git ~/.grunt-init/node

5. Initialise your project

You can use grunt-init to scaffold a project from one of the templates you just installed, or create your own project from scratch. Full templating instructions can be found here: http://gruntjs.com/project-scaffolding

5a. Using grunt-init to scaffold a project

Create a project based on one of the templates you just installed.

Example - Run the following command in the root directory of your project:

grunt-init jquery

This will scaffold a jQuery plugin project, including QUnit unit tests (at the time of writing trying to install the QUnit Grunt plugin as outlined in section 5b1. below will throw up an error - this is a known issue).

In your project directory you should now see a number of folders, including node_modules, plus package.json and Gruntfile.js files.

5b. Or create your own project template

Create a folder for a project. For the purposes of this tutorial let’s call it myproject.

Inside myproject create a folder called src, a folder called build, and a README.md file (or you will get warning messages when you install some of the grunt plugins).

Inside the src folder create a file called myproject.js.

Below are basic examples of package.json and Grunfile.js files.

5b1. package.json

Create a package.json file in the root of your project:

{
    "name": "myproject",
    "version": "0.0.1"
}

Grunt and any grunt plugins you want to use will need to be installed.

You can either install each plugin individually from the command line… For example:

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

The modules will automatically be added to the package.json file, which should now look something like this:

{
    "name": "myproject",
    "version": "0.0.1",
    "devDependencies": {
        "grunt": "~0.4.1",
        "grunt-contrib-nodeunit": "~0.1.2",
        "grunt-contrib-uglify": "~0.1.2"
    }
}

Or, if you already know the versions of the plugins you want (you can find this out on the github repo of each plugin) you can create the package.json file with the devDependencies pre-filled, and then from the command line simply run:

npm install

5b2. Gruntfile.js

Create a Gruntfile.js file in the root of your project:

module.exports = function(grunt) {

  // Project configuration.
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    uglify: {
      options: {
        banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
      },
      build: {
        src: 'src/<%= pkg.name %>.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']);

};

6. Run grunt

Finally, from the command line and in the root directory of your project run grunt:

grunt

All being well you should see the following output:

Running "uglify:build" (uglify) task
File "build/myproject.min.js" created.
Uncompressed size: 10 bytes.
Compressed size: 0 bytes gzipped (0 bytes minified).

Done, without errors.

If you now look in the build folder you should find a minified version of your myproject.js file, called myproject.min.js.

Congratulations, you’ve set up and run Grunt successfully for the first time!

Taking things further

Naturally this introduction only covers the very basics of a Grunt install and project set-up.

Using the methods above and, by following some of the other examples on the Grunt website, you should be able to introduce new automation features, such as ‘linting’ your javascript code, or compiling your .less into minified .css, or setting up a ‘watch’ script to automatically run a new build when changes are detected, and so on.

To learn more I would highly recommend reading through the Grunt documentation. Hopefully if you’ve followed the steps above things should make a bit more sense: http://gruntjs.com/getting-started

If you have any questions or comments about this article, or if you found it useful, please let me know :)