CINXE.COM

<!DOCTYPE html><html lang="en" prefix="og: http://ogp.me/ns#" itemscope itemtype="http://schema.org/WebPage"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><title>Creating tasks - Grunt: The JavaScript Task Runner</title><link rel="stylesheet" href="/css/main.css"><link rel="apple-touch-icon" href="/img/favicons/apple-touch-icon.png" sizes="180x180"><link rel="icon" type="image/png" href="/img/favicons/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="/img/favicons/favicon-16x16.png" sizes="16x16"><link rel="manifest" href="/img/favicons/manifest.json"><link rel="mask-icon" href="/img/favicons/safari-pinned-tab.svg" color="#e48632"><link rel="shortcut icon" href="/img/favicons/favicon.ico" type="image/x-icon"><meta name="msapplication-config" content="/img/favicons/browserconfig.xml"><meta name="theme-color" content="#e48632"><meta property="og:title" content="Creating tasks - Grunt: The JavaScript Task Runner"><meta property="og:type" content="website"><meta property="og:url" content="https://gruntjs.com/"><meta property="og:image" content="https://gruntjs.com/img/og.png"><meta property="og:image:type" content="image/png"><meta property="og:image:width" content="256"><meta property="og:image:height" content="256"><meta name="twitter:card" content="summary_large_image"><meta name="twitter:creator" content="@gruntjs"><meta name="twitter:site" content="@gruntjs"><meta name="twitter:title" content="Creating tasks - Grunt: The JavaScript Task Runner"><meta itemprop="name" content="Grunt"><meta itemprop="image" content="/img/og.png"><link href="/rss" rel="alternate" title="Grunt Blog Feed" type="application/atom+xml"></head><body class="page-docs page-secondary"><div class="banner"> <a href="support">V1.6.1 is the current version, and previous versions are not supported. Upgrade to the latest version or consider other support options.</a></div><div class="navbar navbar-inverse"><div class="navbar-inner"><div class="container"><a class="brand" href="/"></a><div class="nav-collapse collapse"><ul class="nav"><li><a href="/getting-started">Getting Started</a></li><li><a href="/configuring-tasks">Configuring Tasks</a></li><li><a href="/plugins">Plugins</a></li><li><a href="/documentation">Documentation</a></li><li><a href="/support">Support</a></li></ul><form class="navbar-search pull-right"><input class="search-query" type="text" placeholder="Search"></form></div></div></div></div><div class="content"><div class="container creating-tasks"><div class="row-fluid"><div class="span9 page"><div class="hero-unit"><h1>Creating tasks</h1>Tasks are grunt's bread and butter. The stuff you do most often, like <code>jshint</code> or <code>nodeunit</code>. 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. <h2><a class="anchor" href="#alias-tasks" id="alias-tasks"></a>Alias Tasks</h2> 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 tasks in <code>taskList</code> will be run, in the order specified. The <code>taskList</code> argument must be an array of tasks. <pre><code class="lang-js">grunt.registerTask(taskName, [description, ] taskList)</code></pre> This example alias task defines a "default" task whereby the "jshint", "qunit", "concat" and "uglify" tasks are run automatically if Grunt is executed without specifying any tasks: <pre><code class="lang-js">grunt.registerTask('default', ['jshint', 'qunit', 'concat', 'uglify']);</code></pre> Task arguments can be specified as well. In this example, the alias "dist" runs both the "concat" and "uglify" tasks, each with a "dist" argument: <pre><code class="lang-js">grunt.registerTask('dist', ['concat:dist', 'uglify:dist']);</code></pre> <h2><a class="anchor" href="#multi-tasks" id="multi-tasks"></a>Multi Tasks</h2> When a multi task is run, Grunt looks for a property of the same name in the Grunt configuration. Multi-tasks can have multiple configurations, defined using arbitrarily named "targets." Specifying both a task and target like <code>grunt concat:foo</code> or <code>grunt concat:bar</code> will process just the specified target's configuration, while running <code>grunt concat</code> will iterate over all targets, processing each in turn. Note that if a task has been renamed with <a href="/grunt.task#grunt.task.renametask">grunt.task.renameTask</a>, Grunt will look for a property with the new task name in the config object. Most of the contrib tasks, including the <a href="https://github.com/gruntjs/grunt-contrib-jshint#jshint-task">grunt-contrib-jshint plugin jshint task</a> and <a href="https://github.com/gruntjs/grunt-contrib-concat#concat-task">grunt-contrib-concat plugin concat task</a> are multi tasks. <pre><code class="lang-js">grunt.registerMultiTask(taskName, [description, ] taskFunction)</code></pre> Given the specified configuration, this example multi task would log <code>foo: 1,2,3</code> if Grunt was run via <code>grunt log:foo</code>, or it would log <code>bar: hello world</code> if Grunt was run via <code>grunt log:bar</code>. If Grunt was run as <code>grunt log</code> however, it would log <code>foo: 1,2,3</code> then <code>bar: hello world</code> then <code>baz: false</code>. <pre><code class="lang-js">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); });</code></pre> <h2><a class="anchor" href="#basic-tasks" id="basic-tasks"></a>"Basic" Tasks</h2> When a basic task is run, Grunt doesn't look at the configuration or environment鈥攊t just runs the specified task function, passing any specified colon-separated arguments in as function arguments. <pre><code class="lang-js">grunt.registerTask(taskName, [description, ] taskFunction)</code></pre> This example task logs <code>foo, testing 123</code> if Grunt is run via <code>grunt foo:testing:123</code>. If the task is run without arguments as <code>grunt foo</code> the task logs <code>foo, no args</code>. <pre><code class="lang-js">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); } });</code></pre> <h2><a class="anchor" href="#custom-tasks" id="custom-tasks"></a>Custom tasks</h2> You can go crazy with tasks. If your tasks don't follow the "multi task" structure, use a custom task. <pre><code class="lang-js">grunt.registerTask('default', 'My "default" task description.', function() { grunt.log.writeln('Currently running the "default" task.'); });</code></pre> Inside a task, you can run other tasks. <pre><code class="lang-js">grunt.registerTask('foo', 'My "foo" task.', function() { // Enqueue "bar" and "baz" tasks, to run after "foo" finishes, in-order. grunt.task.run('bar', 'baz'); // Or: grunt.task.run(['bar', 'baz']); });</code></pre> Tasks can be asynchronous. <pre><code class="lang-js">grunt.registerTask('asyncfoo', 'My "asyncfoo" task.', function() { // Force task into async mode and grab a handle to the "done" function. var done = this.async(); // Run some sync stuff. grunt.log.writeln('Processing task...'); // And some async stuff. setTimeout(function() { grunt.log.writeln('All done!'); done(); }, 1000); });</code></pre> Tasks can access their own name and arguments. <pre><code class="lang-js">grunt.registerTask('foo', 'My "foo" task.', function(a, b) { grunt.log.writeln(this.name, a, b); }); // Usage: // grunt foo // logs: "foo", undefined, undefined // grunt foo:bar // logs: "foo", "bar", undefined // grunt foo:bar:baz // logs: "foo", "bar", "baz"</code></pre> Tasks can fail if any errors were logged. <pre><code class="lang-js">grunt.registerTask('foo', 'My "foo" task.', function() { if (failureOfSomeKind) { grunt.log.error('This is an error message.'); } // Fail by returning false if this task had errors if (ifErrors) { return false; } grunt.log.writeln('This is the success message'); });</code></pre> When tasks fail, all subsequent tasks will be aborted unless <code>--force</code> was specified. <pre><code class="lang-js">grunt.registerTask('foo', 'My "foo" task.', function() { // Fail synchronously. return false; }); grunt.registerTask('bar', 'My "bar" task.', function() { var done = this.async(); setTimeout(function() { // Fail asynchronously. done(false); }, 1000); });</code></pre> Tasks can be dependent on the successful execution of other tasks. Note that <code>grunt.task.requires</code> won't actually RUN the other task(s). It'll just check to see that it has run and not failed. <pre><code class="lang-js">grunt.registerTask('foo', 'My "foo" task.', function() { return false; }); grunt.registerTask('bar', 'My "bar" task.', function() { // Fail task if "foo" task failed or never ran. grunt.task.requires('foo'); // This code executes if the "foo" task ran successfully. grunt.log.writeln('Hello, world.'); }); // Usage: // grunt foo bar // doesn't log, because foo failed. // ***Note: This is an example of space-separated sequential commands, // (similar to executing two lines of code: `grunt foo` then `grunt bar`) // grunt bar // doesn't log, because foo never ran.</code></pre> Tasks can fail if required configuration properties don't exist. <pre><code class="lang-js">grunt.registerTask('foo', 'My "foo" task.', function() { // Fail task if "meta.name" config prop is missing // Format 1: String grunt.config.requires('meta.name'); // or Format 2: Array grunt.config.requires(['meta', 'name']); // Log... conditionally. grunt.log.writeln('This will only log if meta.name is defined in the config.'); });</code></pre> Tasks can access configuration properties. <pre><code class="lang-js">grunt.registerTask('foo', 'My "foo" task.', function() { // Log the property value. Returns null if the property is undefined. grunt.log.writeln('The meta.name property is: ' + grunt.config('meta.name')); // Also logs the property value. Returns null if the property is undefined. grunt.log.writeln('The meta.name property is: ' + grunt.config(['meta', 'name'])); });</code></pre> Take a look at the <a href="https://github.com/gruntjs/">contrib tasks</a> for more examples. <h2><a class="anchor" href="#cli-options-environment" id="cli-options-environment"></a>CLI options / environment</h2> Use <code>process.env</code> to access the <a href="https://en.wikipedia.org/wiki/Environment_variable">environment variables</a>. Read more about the available command-line options on the <a href="https://gruntjs.com/using-the-cli">Using the CLI</a> page. <h2><a class="anchor" href="#why-doesn-t-my-asynchronous-task-complete" id="why-doesn-t-my-asynchronous-task-complete"></a>Why doesn't my asynchronous task complete?</h2> Chances are this is happening because you have forgotten to call the <a href="https://gruntjs.com/api/inside-tasks#this.async">this.async</a> 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 <code>this.async()</code> within the task body. Note that passing <code>false</code> to the <code>done()</code> function tells Grunt that the task has failed. For example: <pre><code class="lang-js">grunt.registerTask('asyncme', 'My asynchronous task.', function() { var done = this.async(); doSomethingAsync(done); });</code></pre> <h2><a class="anchor" href="#extra-reference" id="extra-reference"></a>Extra Reference</h2> Checkout the <a href="https://gruntjs.com/api">API</a> documentation if you need extra reference to create your tasks. <div class="end-link">Found an error in the documentation? <a href='https://github.com/gruntjs/grunt-docs/issues'>File an issue</a>.</div></div></div><div class="span3"><div class="well sidebar-nav"><ul class="nav nav-list"><li class="nav-header">Documentation</li><li><a href="/getting-started">Getting Started</a></li><li><a href="/configuring-tasks">Configuring Tasks</a></li><li><a href="/sample-gruntfile">Sample Gruntfile</a></li><li><a class="active" href="/creating-tasks">Creating Tasks</a></li><li><a href="/creating-plugins">Creating Plugins</a></li><li><a href="/using-the-cli">Using the CLI</a></li></ul><ul class="nav nav-list"><li class="nav-header">Advanced</li><li><a href="/api">API</a></li><li><a href="/installing-grunt">Installing Grunt</a></li><li><a href="/frequently-asked-questions">Frequently Asked Questions</a></li><li><a href="/project-scaffolding">Project Scaffolding</a></li></ul><ul class="nav nav-list"><li class="nav-header">Community</li><li><a href="/support">Support</a></li><li><a href="/help-resources">Help Resources</a></li><li><a href="/who-uses-grunt">Who uses Grunt</a></li><li><a href="/built-with-grunt-badge">Built with Grunt Badge</a></li><li><a href="/contributing">Contributing</a></li><li><a href="/development-team">Development Team</a></li></ul><ul class="nav nav-list"><li class="nav-header">Migration guides</li><li><a href="/upgrading-from-0.3-to-0.4">Upgrading from 0.3 to 0.4</a></li><li><a href="/upgrading-from-0.4-to-1.0">Upgrading from 0.4 to 1.0</a></li></ul></div></div></div></div></div><footer class="grunt-footer"><div class="inner"><div class="container"><ul class="pull-right"><li><a href="/blog">Blog</a></li><li><a href="/upgrading-from-0.3-to-0.4">Migration Guides</a></li><li><a href="/contributing">Contributing</a></li><li><a href="/development-team">Development Team</a></li><li class="social"><a href="https://github.com/gruntjs/" title="Grunt on GitHub"></a></li><li class="social"><a href="https://twitter.com/gruntjs/" title="Grunt on Twitter"></a></li><li class="social"><a href="/rss" title="Grunt blog RSS feed"></a></li><li class="openjs"><a href="https://openjsf.org/" title="OpenJS Foundation"><img src="/img/openjsf-color-textw.svg" alt="OpenJS Foundation" width="100" height="31"></a></li></ul></div></div></footer></body></html>