Frequently Asked Questions

How do I install grunt?

For general installation instructions, please read the Getting Started guide. If you need more specific information after having read that, read the comprehensive Installing grunt guide.

When will I be able to use in-development feature 'X'?

Installing both published and unpublished development versions of Grunt is covered in the Installing grunt guide.

Does Grunt work on Windows?

Grunt works fine on Windows, because Node.js and npm both work fine on Windows. Usually the problematic part is Cygwin, because it bundles an outdated version of Node.js.

The best way to avoid this issue is to use the msysGit installer to install the git binary and the Node.js installer to install the node and npm binaries, and to use the built-in Windows command prompt or PowerShell instead of Cygwin.

Why doesn't my asynchronous task complete?

Chances are this is happening because you have forgotten to call the this.async method to tell Grunt that your task is asynchronous. For simplicity's sake, Grunt uses a synchronous coding style, which can be switched to asynchronous by calling this.async() within the task body.

Note that passing false to the done() function tells Grunt that the task has failed.

For example:

grunt.registerTask('asyncme', 'My asynchronous task.', function() {
  var done = this.async();
  doSomethingAsync(done);
});

How do I enable shell tab auto-completion?

To enable bash tab auto-completion for grunt, add the following line to your ~/.bashrc file:

eval "$(grunt --completion=bash)"

This assumes that Grunt has been installed globally with npm install -g grunt. Currently, the only supported shell is bash.

How can I share parameters across multiple tasks?

While each task can accept its own parameters, there are a few options available for sharing parameters across multiple tasks.

"Dynamic" alias tasks

This is the preferred method for sharing parameters across multiple tasks.

Whereas alias tasks are necessarily simple, a regular task can use grunt.task.run to make it effectively function as a "dynamic" alias task. In this example, running grunt build:001 on the command line would result in the foo:001, bar:001 and baz:001 tasks being run.

grunt.registerTask('build', 'Run all my build tasks.', function(n) {
  if (n == null) {
    grunt.warn('Build num must be specified, like build:001.');
  }
  grunt.task.run('foo:' + n, 'bar:' + n, 'baz:' + n);
});

-- options

Another way to share a parameter across multiple tasks would be to use grunt.option. In this example, running grunt deploy --target=staging on the command line would cause grunt.option('target') to return "staging".

grunt.registerTask('upload', 'Upload code to specified target.', function() {
  var target = grunt.option('target');
  // do something useful with target here
});
grunt.registerTask('deploy', ['validate', 'upload']);

Note that boolean options can be specified using just a key without a value. For example, running grunt deploy --staging on the command line would cause grunt.option('staging') to return true.

Globals and configs

In other cases, you may want to expose a way to set configuration or global values. In those cases, register a task that sets its arguments as a global or config value.

In this example, running grunt set_global:name:peter set_config:target:staging deploy on the command line would cause global.name to be "peter" and grunt.config('target') to return "staging". Presumably, the deploy task would use those values.

grunt.registerTask('set_global', 'Set a global variable.', function(name, val) {
  global[name] = val;
});

grunt.registerTask('set_config', 'Set a config property.', function(name, val) {
  grunt.config.set(name, val);
});

How I get a stack trace when an error occurs?

Use the --stack option to see stack traces. Such as grunt task --stack

Why am I getting a "Maximum call stack size exceeded" error?

You probably created an alias task with the same name as one of your regular tasks. Example: grunt.registerTask('uglify', ['uglify:my_target']); should be grunt.registerTask('myUglify', ['uglify:my_target']);.

How do I uninstall or remove unwanted plugins?

At least two ways. One way is to use npm uninstall [GRUNT_PLUGIN] --save-dev, this will remove the plugin from your package.json and from node_modules. You may also delete the dependencies you don't want from your package.json manually and then run npm prune.

This is the DOSKEY command you'd use:

DOSKEY grunt=grunt.cmd $*

Found an error in the documentation? File an issue.