A beginner's guide to Grunt
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 [email protected]:gruntjs/grunt-init-commonjs.git ~/.grunt-init/commonjs
git clone [email protected]:gruntjs/grunt-init-gruntfile.git ~/.grunt-init/gruntfile
git clone [email protected]:gruntjs/grunt-init-gruntplugin.git ~/.grunt-init/gruntplugin
git clone [email protected]:gruntjs/grunt-init-jquery.git ~/.grunt-init/jquery
git clone [email protected]: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 :)