Grunt homepage | Documentation table of contents
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');
log.write(awesome);
});
// Register a helper.
grunt.registerHelper('awesome', function() {
return 'awesome!!!';
});
};But these are just examples. For more information, read on.
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.
};Note that the method listed below is also available on the grunt.config object in addition to the grunt object.
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 config.init method.
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 more 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.
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.
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(target) {
grunt.log.writeln(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.
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.
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.
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.
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);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)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.
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".
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".
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.
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.
The number of log.error calls that occurred during this task. This can be used to fail a task if errors occurred during the task.
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".
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".
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'
}
}
});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.
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.
Load tasks and helpers from the specified Npm-installed grunt plugin. If the verion of grunt being run was installed globally via Npm, this will load a global Npm module. If the verion of grunt being run was installed locally via Npm, this will load a local Npm module.
A grunt plugin is really just a folder containing a package.json, a tasks directory, and a few other files. You can very easily create a grunt plugin by using the init task.
grunt.loadNpmTasks(pluginName)This method is an alias for the grunt.task.loadNpmTasks method.
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.
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.
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.
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) // 3This method is an alias for the grunt.task.helper method.
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.
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.
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.
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)- grunt.utils - Miscellaneous utilities, including Underscore.js, Async and Hooker.
- grunt.template - Underscore.js template processing and other template-related methods.
- grunt.task - Register and run tasks and helpers, load external tasks.
- grunt.file - Wildcard expansion, file reading, writing, directory traversing.
- grunt.config - Access project-specific configuration data defined in the grunt.js gruntfile.
- grunt.log, grunt.verbose - Output messages to the console.
- grunt.fail - For when something goes horribly wrong.