Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 0403a1d346
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 411 lines (278 sloc) 21.302 kb

Grunt homepage | Documentation table of contents

The grunt API

Grunt exposes all of its methods and properties on the grunt object that gets passed into the module.exports function exported in your grunt.js gruntfile or in your tasks file.

For example, your project's grunt.js gruntfile might look like this:

module.exports = function(grunt) {

  // Project configuration.
  grunt.initConfig({
    lint: {
      all: ['grunt.js', 'lib/**/*.js', 'test/**/*.js']
    },
    jshint: {
      options: {
        browser: true
      }
    }
  });

  // Load tasks from "grunt-sample" grunt plugin installed via Npm.
  grunt.loadNpmTasks('grunt-sample');

  // Default task.
  grunt.registerTask('default', 'lint sample');

};

And if you're creating a grunt plugin or just organizing tasks into a folder, a custom tasks file might look like this:

module.exports = function(grunt) {

  // Create a new task.
  grunt.registerTask('awesome', 'Print out "awesome!!!"', function() {
    var awesome = grunt.helper('awesome');
    grunt.log.write(awesome);
  });

  // Register a helper.
  grunt.registerHelper('awesome', function() {
    return 'awesome!!!';
  });

};

But these are just examples. For more information, read on.

A Very Important Note

Your grunt.js gruntfile or tasks file must contain this code, once and only once. If it doesn't, things won't work. For the sake of brevity, this "wrapper" code has been omitted from all future examples on this page, but it needs to be there. Like in the previous examples.

module.exports = function(grunt) {
  // Your grunt code goes in here.
};

Config

Note that the method listed below is also available on the grunt.config object in addition to the grunt object.

grunt.initConfig

Initialize a configuration object for the current project. The specified configObject is used by tasks and helpers and can also be accessed using the grunt.config method. Nearly every project's grunt.js gruntfile will call this method.

Note that any specified <config> and <json> directives will be automatically processed when the config object is initialized.

grunt.initConfig(configObject)

This example contains sample config data for the lint task:

grunt.initConfig({
  lint: {
    all: ['lib/*.js', 'test/*.js', 'grunt.js']
  }
});

See the configuring grunt page for more configuration examples.

This method is an alias for the grunt.config.init method.

Creating Tasks

Tasks are grunt's bread and butter. The stuff you do most often, like lint or test. Every time grunt is run, you specify one or more tasks to run, which tells grunt what you'd like it to do.

If you don't specify a task, but a task named "default" has been defined, that task will run (unsurprisingly) by default.

Note that the methods listed below are also available on the grunt.task object in addition to the grunt object.

grunt.registerTask

Register an "alias task" or a task function. This method supports the following two signatures:

Alias task

If a task list is specified, the new task will be an alias for one or more other tasks. Whenever this "alias task" is run, every specified task in taskList will be run, in the order specified. The taskList argument can be a space-separated string or an array of task names.

grunt.registerTask(taskName, taskList)

This example alias task defines a "default" task whereby the "lint", "qunit", "concat" and "min" tasks are run automatically if grunt is executed without any tasks specified:

task.registerTask('default', 'lint qunit concat min');

Function task

If a description and taskFunction are passed, the specified function will be executed whenever the task is run. In addition, the specified description will be shown when grunt --help is run. Task-specific properties and methods are available inside the task function as properties of the this object. The task function can return false to indicate that the task has failed.

Note that the grunt.registerMultiTask method, explained below, can be used to define a special type of task known as a "multi task."

grunt.registerTask(taskName, description, taskFunction)

This example task logs foo, testing 123 if grunt is run via grunt foo:testing:123. If the task is run without arguments as grunt foo the task logs foo, no args.

grunt.registerTask('foo', 'A sample task that logs stuff.', function(arg1, arg2) {
  if (arguments.length === 0) {
    grunt.log.writeln(this.name + ", no args");
  } else {
    grunt.log.writeln(this.name + ", " + arg1 + " " + arg2);
  }
});

See the creating tasks documentation for more examples of tasks and alias tasks.

This method is an alias for the grunt.task.registerTask method.

grunt.registerMultiTask

Register a "multi task." A multi task is a task that implicitly iterates over all of its named sub-properties (AKA targets) if no target was specified. In addition to the default properties and methods, extra multi task-specific properties are available inside the task function as properties of the this object.

Many of the built-in tasks, including the lint task, concat task and min task are multi tasks.

grunt.registerMultiTask(taskName, description, taskFunction)

Given the specified configuration, this example multi task would log foo: 1,2,3 if grunt was run via grunt log:foo, or it would log bar: hello world if grunt was run via grunt log:bar. If grunt was run as grunt log however, it would log foo: 1,2,3 then bar: hello world then baz: false.

grunt.initConfig({
  log: {
    foo: [1, 2, 3],
    bar: 'hello world',
    baz: false
  }
});

grunt.registerMultiTask('log', 'Log stuff.', function() {
  grunt.log.writeln(this.target + ': ' + this.data);
});

See the creating tasks documentation for more examples of multi tasks.

This method is an alias for the grunt.task.registerMultiTask method.

grunt.registerInitTask

Register an "init task." An init task is a task that doesn't require any configuration data, and as such will still run even if grunt can't find a grunt.js gruntfile. The included init task is an example of an "init task."

grunt.registerInitTask(taskName, description, taskFunction)

For an init task example, see the init task source.

This method is an alias for the grunt.task.registerInitTask method.

grunt.renameTask

Rename a task. This might be useful if you want to override the default behavior of a task, while retaining the old name.

grunt.renameTask(oldname, newname)

This method is an alias for the grunt.task.renameTask method.

Inside Tasks

An object is made available as this inside each task function that contains a number of useful task-specific properties and methods. This same object is also exposed as grunt.task.current for use in templates.

this.async / grunt.task.current.async

If a task is asynchronous, this method must be invoked to instruct grunt to wait. It returns a handle to a "done" function that should be called when the task has completed. false can be passed to the done function to indicate that the task has failed. If this method isn't invoked, the task executes synchronously.

// Tell grunt this task is asynchronous.
var done = this.async();
// Your async code.
setTimeout(function() {
  // Let's simulate an error, sometimes.
  var success = Math.random() > 0.5;
  // All done!
  done(success);
}, 1000);

this.requires / grunt.task.current.requires

If one task depends on the successful completion of another task (or tasks), this method can be used to force grunt to abort if the other task didn't run, or if the other task failed. The task list can be a space-separated string, an array of task names, or individual task name arguments.

Note that this won't actually run the specified task(s), it will just fail the current task if they haven't already run successfully.

this.requires(taskList)

this.requiresConfig / grunt.task.current.requiresConfig

Fail the current task if one or more required config properties is missing. One or more string or array config properties may be specified.

this.requiresConfig(prop [, prop [, ...]])

See the grunt.config documentation for more information about config properties.

This method is an alias for the grunt.config.requires method.

this.name / grunt.task.current.name

The name of the task, as defined in grunt.registerTask. For example, if a "sample" task was run as grunt sample or grunt sample:foo, inside the task function, this.name would be "sample".

this.nameArgs / grunt.task.current.nameArgs

The name of the task, as specified with any colon-separated arguments or flags on the command-line. For example, if a "sample" task was run as grunt sample:foo, inside the task function, this.nameArgs would be "sample:foo".

this.args / grunt.task.current.args

An array of arguments passed to the task. For example, if a "sample" task was run as grunt sample:foo:bar, inside the task function, this.args would be ["foo", "bar"]. Note that in multi tasks, the target is removed from the this.args array and is not passed into the task function.

this.flags / grunt.task.current.flags

An object generated from the arguments passed to the task. For example, if a "sample" task was run as grunt sample:foo:bar, inside the task function, this.flags would be {foo: true, bar: true}. In a multi task, the target name is not set as a flag.

this.errorCount / grunt.task.current.errorCount

The number of grunt.log.error calls that occurred during this task. This can be used to fail a task if errors occurred during the task.

Inside Multi Tasks

this.target / grunt.task.current.target

In a multi task, this is the name of the target currently being iterated over. For example, if a "sample" multi task was run as grunt sample:foo with the config data {sample: {foo: "bar"}}, inside the task function, this.target would be "foo".

this.data / grunt.task.current.data

In a multi task, this is the actual data stored in the grunt config object for the given target. For example, if a "sample" multi task was run as grunt sample:foo with the config data {sample: {foo: "bar"}}, inside the task function, this.data would be "bar".

this.file / grunt.task.current.file

In a multi task, target data can be stored in two different formats. A relatively basic "compact" format and a much more flexible "full" format. When the compact format is used, that key and value are made available as this.file.dest and this.file.src, respectively. When the full format is used, the specified src and dest values are used for this.file.dest and this.file.src.

Note that while grunt supports expanding templates for both src and dest, they only work for the dest file path when the full format is used.

grunt.initConfig({
  concat: {
    // This is the "compact" format.
    'dist/built.js': ['src/file1.js', 'src/file2.js'],
    // This is the "full" format.
    built: {
      src: ['src/file1.js', 'src/file2.js'],
      dest: 'dist/built.js'
    }
  }
});

Loading Externally-Defined Tasks

For most projects, tasks and helpers will be defined in the grunt.js gruntfile. For larger projects, or in cases where tasks and helpers need to be shared across projects, tasks can be loaded from one or more external directories or Npm-installed grunt plugins.

Note that the methods listed below are also available on the grunt.task object in addition to the grunt object.

grunt.loadTasks

Load task-related files from the specified directory, relative to the grunt.js gruntfile. This method can be used to load task-related files from a local grunt plugin by specifying the path to that plugin's "tasks" subdirectory.

grunt.loadTasks(tasksPath)

This method is an alias for the grunt.task.loadTasks method.

grunt.loadNpmTasks

Load tasks and helpers from the specified grunt plugin. This plugin must be installed locally via npm, and must be relative to the grunt.js gruntfile. Grunt plugins can be created by using the gruntplugin init template.

grunt.loadNpmTasks(pluginName)

This method is an alias for the grunt.task.loadNpmTasks method.

Defining and Executing Helpers

Helpers are utility functions that can be used by any task.

For example, in the min task, the majority of the actual minification work is done in an uglify helper, so that other tasks can utilize that minification code if they want to.

See the list of built-in helpers for examples.

Note that the methods listed below are also available on the grunt.task object in addition to the grunt object.

grunt.registerHelper

Register a helper function that can be used by any task. When called as a directive, this.directive will be true inside of the helper.

grunt.registerHelper(helperName, helperFunction)

In this example helper, the numbers 1 and 2 are passed in and the value 3 is returned.

grunt.registerHelper('add_two_nums', function(a, b) {
  return a + b;
});

This method is an alias for the grunt.task.registerHelper method.

grunt.renameHelper

Rename a helper. This might be useful if you want to override the default behavior of a helper, while retaining the old name (to avoid having to completely recreate an already-made task just because you needed to override or extend a built-in helper).

grunt.renameHelper(oldname, newname)

This method is an alias for the grunt.task.renameHelper method.

grunt.helper

Invoke a registered helper function.

grunt.helper(helperName [, arguments...])

In this example, the previously defined add_two_nums helper is invoked.

grunt.helper('add_two_nums', 1, 2) // 3

This method is an alias for the grunt.task.helper method.

Warnings and Fatal Errors

If something explodes (or is about to explode) inside a helper or task, it can force grunt to abort. See the exit codes documentation for a list of all built-in grunt exit codes.

grunt.warn

Display a warning and abort grunt immediately. Grunt will continue processing tasks if the --force command-line option was specified. The error argument can be a string message or an error object.

grunt.warn(error [, errorcode])

If --debug 9 is specified on the command-line and an error object was specified, a stack trace will be logged.

This method is an alias for the grunt.fail.warn method.

grunt.fatal

Display a warning and abort grunt immediately. The error argument can be a string message or an error object.

grunt.fail(error [, errorcode])

If --debug 9 is specified on the command-line and an error object was specified, a stack trace will be logged.

This method is an alias for the grunt.fail.fatal method.

Command-line Options

grunt.option

Retrieve the value of a command-line option, eg. debug. Note that for each command-line option, the inverse can be tested, eg. no-debug.

grunt.option(optionName)

Miscellaneous

grunt.version

The current grunt version, as a string.

grunt.version

grunt.npmTasks

Inside a grunt plugin bin script, this method must be called to inform grunt where to look for that plugin's tasks files. The npmModuleName must be the grunt plugin's Npm module name. The gruntplugin init template, will automatically configure this for you.

grunt.npmTasks(npmModuleName)

Other Methods

Something went wrong with that request. Please try again.