Grunt: JavaScript Task Runner Guide

Before task runners existed, keeping JavaScript codebases clean was manual and repetitive. Concatenating files, compiling Sass to CSS, minifying assets: each step ran by hand every time something changed.

Tools like CodeKit helped for a while. Then Node.js arrived and made a new class of automation tools possible. Grunt is one of them.

What is Grunt?

Grunt is a command-line task runner built on Node.js. It runs configured tasks from the terminal so you never repeat the same manual steps.

The Grunt plugin ecosystem covers most common needs: compile LESS or Sass, concatenate JavaScript, minify assets, run tests, version files, and upload to a server. When a source file changes, one command handles the entire chain.

Grunt is not the only option. Gulp and Broccoli exist and have active communities. Grunt's appeal is its configuration-over-code approach: tasks are declared as plain JavaScript objects, which makes the setup readable to anyone on the team, even developers who are not deeply familiar with Node.js streams.

Setting Up Grunt

Grunt requires Node.js. Install it first if you have not already.

Once Node.js is installed, install the Grunt CLI globally:

npm install -g grunt-cli

This only runs once per machine. After that, create two files in the root of your project: package.json and Gruntfile.js.

The package.json File

A minimal package.json for a Grunt project:

{
  "name": "MyGrunt",
  "version": "1.0.0",
  "author": "Reader",
  "private": true,
  "devDependencies": {
    "grunt": "~1.6.0"
  }
}

The devDependencies block tells Node.js that Grunt is required for development. Run the following to install it:

npm install

After installation, a node_modules folder appears in the project root containing the local Grunt copy.

Creating Gruntfile.js

Gruntfile.js lives in the project root. A basic working version:

module.exports = function(grunt) {
  grunt.registerTask('default', function() {
    grunt.log.writeln('Hello World!');
  });
};

Run this from the project root:

grunt

You see Hello World! printed to the terminal.

Here is what happens: Grunt loads Gruntfile.js and calls the function exported via module.exports, passing the grunt object as the only argument. registerTask registers a new task named default. The default task is special: it runs whenever you call grunt with no additional arguments. grunt.log.writeln writes a line to the console.

If you had registered the task as grunt.registerTask('hello', ...) instead, you would call grunt hello to run it.

Grunt and Configuration Parameters

Tasks can accept parameters. Extend the default task to accept a name:

module.exports = function(grunt) {
  grunt.registerTask('default', function(name) {
    grunt.log.writeln('Hello ' + name + '!');
  });
};

Pass a parameter like this:

grunt default:Alice

The terminal outputs:

Running "default:Alice" (default) task
Hello Alice!

Without a parameter, name is undefined, so the greeting reads Hello undefined!. Fix that with a configuration default using grunt.initConfig:

module.exports = function(grunt) {
  grunt.initConfig({
    values: {
      greeting: 'World'
    }
  });

  grunt.registerTask('default', function(name) {
    name = name || grunt.config.get('values').greeting;
    grunt.log.writeln('Hello ' + name + '!');
  });
};

initConfig stores values Grunt can read back anywhere in the file. When no parameter is passed, the task falls back to values.greeting.

You can also use configuration values inside template strings via grunt.template.process:

grunt.registerTask('hello-world', function() {
  grunt.log.writeln(
    grunt.template.process('Hello <%= values.greeting %>')
  );
});

To move the configuration into a separate file, create config.json:

{
  "values": {
    "greeting": "World"
  }
}

Then load it in Gruntfile.js:

module.exports = function(grunt) {
  grunt.initConfig(grunt.file.readJSON('config.json'));

  grunt.registerTask('hello-world', function() {
    grunt.log.writeln(
      grunt.template.process('Hello <%= values.greeting %>')
    );
  });
};

grunt.file.readJSON reads the file path and returns a JavaScript object. The task behaves identically to the inline version.

A Real Use Case

The previous examples demonstrate the API. Here is a practical scenario: a site with two JavaScript files, funciones.js and app.js, that need to be concatenated and minified into a single production file.

Project structure:

.
+-- Gruntfile.js
+-- config.json
+-- node_modules
|   +-- grunt
+-- web
    +-- index.html
    +-- js
        +-- app.js
        +-- funciones.js

Two Grunt plugins handle this:

• grunt-contrib-concat concatenates multiple files into one.
• grunt-contrib-uglify minifies JavaScript so the output file is smaller.

Install both at once:

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

The --save-dev flag adds them to devDependencies in package.json automatically.

Configuration

Load the installed tasks in Gruntfile.js using loadNpmTasks:

module.exports = function(grunt) {
  grunt.loadNpmTasks('grunt-contrib-concat');
  grunt.loadNpmTasks('grunt-contrib-uglify');
};

Next, add path settings and task configuration via initConfig. Storing paths in a routes object means you update one place when the folder structure changes:

module.exports = function(grunt) {
  grunt.initConfig({
    routes: {
      root: 'web',
      js: '<%= routes.root %>/js'
    },
    concat: {
      app: {
        src: [
          '<%= routes.js %>/funciones.js',
          '<%= routes.js %>/app.js'
        ],
        dest: '<%= routes.js %>/app.min.js'
      }
    },
    uglify: {
      app: {
        src: '<%= concat.app.dest %>',
        dest: '<%= concat.app.dest %>'
      }
    }
  });

  grunt.loadNpmTasks('grunt-contrib-concat');
  grunt.loadNpmTasks('grunt-contrib-uglify');
};

The concat task defines a target called app. A task can have multiple targets: to run a specific one, use the syntax grunt concat:app. Running grunt concat alone runs all targets in order.

The uglify task reads its source from concat.app.dest using the template system, so the paths stay in sync automatically.

Wiring Tasks Together

Register an alias that runs both tasks in order:

grunt.registerTask('scripts', ['concat:app', 'uglify:app']);
grunt.registerTask('default', ['scripts']);

Running grunt scripts executes concatenation and then minification. Adding scripts to the default alias means a bare grunt command runs the entire pipeline.

The complete Gruntfile.js:

module.exports = function(grunt) {
  grunt.initConfig({
    routes: {
      root: 'web',
      js: '<%= routes.root %>/js'
    },
    concat: {
      app: {
        src: [
          '<%= routes.js %>/funciones.js',
          '<%= routes.js %>/app.js'
        ],
        dest: '<%= routes.js %>/app.min.js'
      }
    },
    uglify: {
      app: {
        src: '<%= concat.app.dest %>',
        dest: '<%= concat.app.dest %>'
      }
    }
  });

  grunt.registerTask('scripts', ['concat:app', 'uglify:app']);
  grunt.registerTask('default', ['scripts']);

  grunt.loadNpmTasks('grunt-contrib-concat');
  grunt.loadNpmTasks('grunt-contrib-uglify');
};

Running grunt from the project root concatenates funciones.js and app.js into app.min.js, then minifies that file in place.

Group tasks by subject area and create named aliases for each group. That keeps task execution predictable and makes the file easy to extend later.

---

If you are working through a Node.js or JavaScript assignment and need a hand, the team at GeeksProgramming covers web tooling, build pipelines, and programming homework help. You can also read more about NodeJS Installation and Hello World Program or explore Functional Programming in JavaScript.