Get Going with Grunt

In this guide you will install Grunt on OS X, create a new project and set up tasks for running autoprefixer, Sass and Livereload whenever a file changes.

You can just follow the directions and get up and running quickly, but I've also included some of the problems I ran into along the way and how I worked around them. I've done this mostly for the poor soul desperately Googling "No "sass" targets found". If that's you, maybe you'll find the answer you are looking for in here.

If you run into any problems along the way or have a suggestion for an improvement, shoot me an email ([email protected]) or tell me on Twitter (@sfioritto) so I can update the guide.

NOTE: These directions are specifically for OS X, but if you're on Windows or Linux, once you get NPM installed the directions should be pretty similar.

Step 1: Upgrade Xcode, install/reinstall npm

Make sure you have the latest version of Xcode, because if you're like me your version is ancient. You also need npm, (package manager for Node.js), to install grunt and grunt plugins.

I use Homebrew to install npm. In my case I had to uninstall and reinstall npm. When I tried to install grunt the first time, the grunt command was not added to my path, which should have happened automatically. Rather than forcing it to work, I figured I must have messed up the initial install of npm, so I reinstalled and sure enough that fixed the problem.

Open up your command line and install npm.

brew uninstall npm
brew install npm

Step 2: Install grunt command line tools

In the command line use npm to install the grunt command line tools.

npm install -g grunt-cli

You may be thinking to yourself, "But wait, I haven't installed grunt yet. When do I install grunt?"

Grunt is not an application that you install and run in the background like Codekit. It's just a piece of code that sits in your project's folder.

You can think of it as a script to help you build your project, and you need a copy of this script for each of your projects. We'll get to that part shortly.

Step 3: Install grunt-init

NOTE: I'm assuming you have git installed.

npm install -g grunt-init
mkdir ~/.grunt-init
git clone https://github.com/gruntjs/grunt-init-gruntfile.git ~/.grunt-init/gruntfile

In your project directory, run this command:

grunt-init gruntfile

Answer the questions like so:

After reading the docs I noticed most of learning "grunt" is setting up two configuration files, package.json and Gruntfile.js. For my purposes I just wanted to get up and running quickly, so I started searching around for basic templates of these two files I could use instead of creating them by hand. That's where grunt-init comes in.

The grunt-init plugin is like a little mini-framework in and of itself. You can start all kinds of projects, but the 'gruntfile' project is the most basic I could find, so you'll start with that.

The downside of using grunt-init is there is a bunch of extra stuff in the config files you don't need, and it created a few extra headaches. But this is a "Getting Started" guide, not "Learn everything about Grunt" guide, so moving on.

Step 4: "Install" grunt

In your project's directory, run this command:

npm install grunt --save-dev

If you'll recall, this doesn't actually "install" grunt, it just adds the grunt "script" to your project. You'll have to do this for each project.

(There's probably a good way to share grunt configurations across projects easily, but I didn't look into it).

Step 5: Add autoprefixer

In your project's directory:

npm install grunt-autoprefixer --save-dev

Open up Gruntfile.js, (it's in your project directory, you created it when you ran grunt-init), and find the section toward the bottom with the "loadNpmTasks" function calls and add a task:

grunt.loadNpmTasks('grunt-autoprefixer');

Step 6: Sass and Grunt Watch

In your project directory, install the Sass plugin and Grunt Watch with npm:

npm install grunt-sass --save-dev
npm install grunt-contrib-watch --save-dev

And just like with autoprefixer, add it to your Gruntfile.

grunt.loadNpmTasks('grunt-contrib-watch');
grunt.loadNpmTasks('grunt-sass');

Step 7: Remove extra junk from Gruntfile.js

At this point the Gruntfile generated by grunt-init becomes a liability. There are a few things you have to remove, otherwise grunt won't run.

Remove these lines:

grunt-contrib-concat
grunt-contrib-uglify
grunt-contrib-qunit
grunt-contrib-jshint

If you don't remove these lines and try to run grunt, you'll warnings like

"Aborted due to warnings"

or

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

Step 8: tweak the watch section

In Gruntfile.js, change this line:

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

To this:

grunt.registerTask('default', ['watch', 'autoprefixer', 'sass']);

Make your watch section look like this, (you will have to delete some sections):

watch: {
    sass: {
        files: ['*.scss'],
        tasks: ['sass', 'autoprefixer'],
        options: {
            spawn: false,
            livereload: true
        }
    },
    html: {
        files: ['*.html'],
        options: {
            spawn: false,
            livereload: true
        }
    }
}

The sass section says whenever a .scss file changes, run the Sass task then the autoprefixer task and then trigger a livereload of the browser. The HTML section is there so whenever an HTML file changes, the browser will livereload.

Step 394: Configuration

Okay okay, it's only step 9 but it sure feels like more.

You need to configure the Sass and autoprefixer plugins. For my project all of my .scss files live in the top directory of the project and I compile them into the same folder. Autoprefixed css will go into a css folder.

So in the initConfig section of the Gruntfile.js, add this, (make adjustments as necessary, I only have one .scss file, main.scss):

sass: {
        dist: {
            files: {
                'main.css': 'main.scss'
            }
        }
    }

Then add this for autoprefixer:

autoprefixer: {
            // prefix all files
            multiple_files: {
                expand: true,
                flatten: true,
                src: '*.css',
                dest: 'css/'
            }
        },

You can do set this up differently, and you probably will, this is a pretty dumb setup but I just needed to get something working for a quick one-off demo. Bigger projects deserve more thought.

Step 10: live reload

Livereload is already configured in Grunt if you followed the directions up to this point. But you still have to either add a script tag to your html, setup some sort of Grunt middleware to add the tag as a watch task or install an extension.

<script src="//localhost:35729/livereload.js"></script>

The problem with the script is you have to remove it before you deploy the production version of your project. Pretty easy if you are using some sort of template language, but not easy with pure HTML. There's something called 'middleware' you can install, but I just added the livereload extension to Chrome.

Step 11: Run Grunt

In your project directory, enter the command 'grunt'. Hit enter. It should look something like this:

Download my Gruntfile

Can't get it to work? Compare your Gruntfile with mine. and see if there are any obvious differences.

Conclusion

A few months ago I wrote a little essay for my newsletter that maybe you shouldn't use Grunt. For 30 bucks you could just grab Codekit and be compiling Sass and live-reloading your projects in a matter of minutes. Compare that to the convoluted first experience of Grunt. Is it worth it?

Hopefully this little guide saved you a few hours of fruitless googling! And if you like this and want more like it, sign up for my newsletter.

Sketching with CSS will teach you how to design in the browser.

Sketching with CSS

Blow away your clients with your fast turnaround time. Bend CSS layouts to your will. Show your clients comps they can actually click on.

Get a free chapter and an 8 day email course on rapid prototyping in the browser.

Share this article with your friends:

Hey there, I'm Sean.

I'm probably a lot like you. I make stuff for the web. I have a CS degree, but the last 8 years of my career have been a more potent teacher.

Sean Fioritto

Recently, I wrote a book on web development called Sketching with CSS. I also run a training company for developers. I'm an author in Smashing Magazine and I've written some cool open source projects.

Today, I'm an entrepreneur. In the not so distant past I did the usual 9-5 thing doing web development for a couple of big companies.

I'd love to meet you on Twitter.

You can also email me: [email protected]