Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 334 lines (230 sloc) 14.122 kb
7ee61b69 »
2012-02-04 Docs reorganization.
1 [Grunt homepage](https://github.com/cowboy/grunt) | [Documentation table of contents](toc.md)
2
3 # The grunt API
4
82a6799c »
2012-03-19 More docs.
5 Grunt exposes all of its methods and properties on the `grunt` object that gets passed into the `exports.config` function exported in your [grunt.js gruntfile](configuring.md) or the `exports.tasks` function exported in your [tasks file](tasks_creating.md).
dbaee9c8 »
2012-03-19 More docs.
6
82a6799c »
2012-03-19 More docs.
7 For example, your project's [grunt.js gruntfile](configuring.md) might look like this:
dbaee9c8 »
2012-03-19 More docs.
8
9 ```javascript
10 exports.config = function(grunt) {
ee1939e9 »
2012-03-19 More docs.
11
12 // Project configuration.
13 grunt.initConfig({
14 lint: {
15 all: ['grunt.js', 'lib/**/*.js''test/**/*.js']
16 },
17 jshint: {
18 options: {
19 browser: true
20 }
21 }
22 });
23
b2a86d87 »
2012-03-19 More docs.
24 // Load tasks from "grunt-sample" grunt plugin installed via Npm.
ee1939e9 »
2012-03-19 More docs.
25 grunt.loadNpmTasks('grunt-sample');
26
27 // Default task.
28 grunt.registerTask('default', 'lint sample');
29
dbaee9c8 »
2012-03-19 More docs.
30 };
31 ```
32
c8e22b44 »
2012-03-19 More docs.
33 And if you're creating a [grunt plugin](plugins.md) or just organizing tasks into a folder, a [custom tasks file](tasks_creating.md) might look like this:
dbaee9c8 »
2012-03-19 More docs.
34
35 ```javascript
36 exports.tasks = function(grunt) {
ee1939e9 »
2012-03-19 More docs.
37
38 // Create a new task.
39 grunt.registerTask('awesome', 'Print out "awesome!!!"', function() {
40 var awesome = grunt.helper('awesome');
41 log.write(awesome);
42 });
43
44 // Register a helper.
45 grunt.registerHelper('awesome', function() {
46 return 'awesome!!!';
47 });
48
dbaee9c8 »
2012-03-19 More docs.
49 };
50 ```
51
16c967bd »
2012-03-19 More docs.
52 But these are just examples. For more information, take a look at the API documentation:
5b737373 »
2012-03-19 More docs.
53
48bcd441 »
2012-03-19 More docs.
54 ## Config
d7920eaa »
2012-03-20 More docs.
55 _Note that the method listed below is also available on the [grunt.config](api_config.md) object in addition to the `grunt` object._
2b76fd5d »
2012-03-20 More docs.
56
80581c20 »
2012-03-19 More docs.
57
48bcd441 »
2012-03-19 More docs.
58 ### grunt.initConfig
82a6799c »
2012-03-19 More docs.
59 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](api_config.md) method. Nearly every project's [grunt.js gruntfile](configuring.md) will call this method.
dbaee9c8 »
2012-03-19 More docs.
60
61 ```javascript
34274e30 »
2012-03-19 More docs.
62 grunt.initConfig(configObject)
63 ```
64
31950ddd »
2012-03-19 More docs.
65 This example contains sample config data for the [lint task](task_lint.md):
34274e30 »
2012-03-19 More docs.
66
67 ```javascript
68 grunt.initConfig({
69 lint: {
70 all: ['lib/*.js', 'test/*.js', 'grunt.js']
71 }
72 });
dbaee9c8 »
2012-03-19 More docs.
73 ```
74
5a414664 »
2012-03-19 More docs.
75 See the [configuring grunt](configuring.md) page for more configuration examples.
29b12b96 »
2012-03-19 More docs.
76
fbc09866 »
2012-03-19 More docs.
77 _This method is an alias for the [config.init](api_config.md) method._
dbaee9c8 »
2012-03-19 More docs.
78
48bcd441 »
2012-03-19 More docs.
79
0e2160ef »
2012-03-19 More docs.
80 ## Creating Tasks
d7920eaa »
2012-03-20 More docs.
81 _Note that the methods listed below are also available on the [grunt.task](api_task.md) object in addition to the `grunt` object._
82
80581c20 »
2012-03-19 More docs.
83
48bcd441 »
2012-03-19 More docs.
84 ### grunt.registerTask
e2bebb66 »
2012-03-19 More docs.
85 Register an "alias task" or a task function. This method supports the following two signatures:
dbaee9c8 »
2012-03-19 More docs.
86
cc089188 »
2012-03-19 More docs.
87 **Alias task**
5c469024 »
2012-03-19 More docs.
88
f353857d »
2012-03-20 More docs.
89 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.
dbaee9c8 »
2012-03-19 More docs.
90
91 ```javascript
34274e30 »
2012-03-19 More docs.
92 grunt.registerTask(taskName, taskList)
f5311130 »
2012-03-19 More docs.
93 ```
94
e2bebb66 »
2012-03-19 More docs.
95 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:
96
97 ```javascript
98 task.registerTask('default', 'lint qunit concat min');
99 ```
100
cc089188 »
2012-03-19 More docs.
101 **Function task**
5c469024 »
2012-03-19 More docs.
102
f683ef95 »
2012-03-20 More docs.
103 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.
80581c20 »
2012-03-19 More docs.
104
105 Note that the `grunt.registerMultiTask` method, explained below, can be used to define a special type of task known as a "multi task."
f5311130 »
2012-03-19 More docs.
106
107 ```javascript
34274e30 »
2012-03-19 More docs.
108 grunt.registerTask(taskName, description, taskFunction)
dbaee9c8 »
2012-03-19 More docs.
109 ```
110
451428fd »
2012-03-19 More docs.
111 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`.
5dacc941 »
2012-03-19 More docs.
112
113 ```javascript
114 grunt.registerTask('foo', 'A sample task that logs stuff.', function(arg1, arg2) {
115 if (arguments.length === 0) {
116 grunt.log.writeln(this.name + ", no args");
117 } else {
118 grunt.log.writeln(this.name + ", " + arg1 + " " + arg2);
119 }
120 });
121 ```
122
82a6799c »
2012-03-19 More docs.
123 See the [creating tasks](tasks_creating.md) documentation for more examples of tasks and alias tasks.
f5311130 »
2012-03-19 More docs.
124
78099bbb »
2012-03-20 More docs.
125 _This method is an alias for the [grunt.task.registerTask](api_task.md) method._
f5311130 »
2012-03-19 More docs.
126
127
48bcd441 »
2012-03-19 More docs.
128 ### grunt.registerMultiTask
451428fd »
2012-03-19 More docs.
129 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.
dbaee9c8 »
2012-03-19 More docs.
130
31950ddd »
2012-03-19 More docs.
131 Many of the built-in tasks, including the [lint task](task_lint.md), [concat task](task_concat.md) and [min task](task_min.md) are multi tasks.
dbaee9c8 »
2012-03-19 More docs.
132
133 ```javascript
34274e30 »
2012-03-19 More docs.
134 grunt.registerMultiTask(taskName, description, taskFunction)
dbaee9c8 »
2012-03-19 More docs.
135 ```
136
82a6799c »
2012-03-19 More docs.
137 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 `grunt baz: false`.
451428fd »
2012-03-19 More docs.
138
139 ```javascript
140 grunt.initConfig({
141 log: {
142 foo: [1, 2, 3],
143 bar: 'hello world',
144 baz: false
145 }
146 });
147
148 grunt.registerMultiTask('log', 'Log stuff.', function(target) {
149 grunt.log.writeln(target + ': ' + this.data);
150 });
151 ```
152
82a6799c »
2012-03-19 More docs.
153 See the [creating tasks](tasks_creating.md) documentation for more examples of multi tasks.
80581c20 »
2012-03-19 More docs.
154
78099bbb »
2012-03-20 More docs.
155 _This method is an alias for the [grunt.task.registerMultiTask](api_task.md) method._
80581c20 »
2012-03-19 More docs.
156
157
48bcd441 »
2012-03-19 More docs.
158 ### grunt.registerInitTask
fd452388 »
2012-03-19 More docs.
159 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](configuring.md). The [init task](task_init.md) is an example of an init task.
dbaee9c8 »
2012-03-19 More docs.
160
161 ```javascript
34274e30 »
2012-03-19 More docs.
162 grunt.registerInitTask(taskName, description, taskFunction)
dbaee9c8 »
2012-03-19 More docs.
163 ```
164
fd452388 »
2012-03-19 More docs.
165 For an init task example, see the [init task source](../tasks/init.js).
82a6799c »
2012-03-19 More docs.
166
78099bbb »
2012-03-20 More docs.
167 _This method is an alias for the [grunt.task.registerInitTask](api_task.md) method._
5be5bf32 »
2012-03-19 More docs.
168
78099bbb »
2012-03-20 More docs.
169 ### grunt.renameTask
170 Rename a task. This might be useful if you want to override the default behavior of a task, while retaining the old name.
171
172 ```javascript
173 grunt.renameTask(oldname, newname)
174 ```
175
176 _This method is an alias for the [grunt.task.renameTask](api_task.md) method._
5be5bf32 »
2012-03-19 More docs.
177
18e3d037 »
2012-03-19 More docs.
178 ## Inside Tasks
5be5bf32 »
2012-03-19 More docs.
179
29a06f8d »
2012-03-20 More docs.
180 ### this / grunt.task.current
fcf6e677 »
2012-03-20 More docs.
181 An object is made available as `this` inside each task function that contains a number of useful task-specific properties and methods. It is also exposed as `grunt.task.current` for use in [templates](api_template.md).
29a06f8d »
2012-03-20 More docs.
182
7e13cf48 »
2012-03-20 More docs.
183 ### this.async / grunt.task.current.async
62a16c09 »
2012-03-19 More docs.
184 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.
148d6ee6 »
2012-03-19 More docs.
185
186 ```javascript
187 // Tell grunt this task is asynchronous.
188 var done = this.async();
189 // Your async code.
190 setTimeout(function() {
d5405a49 »
2012-03-19 More docs.
191 // Let's simulate an error, sometimes.
36cf5074 »
2012-03-19 More docs.
192 var success = Math.random() > 0.5;
62a16c09 »
2012-03-19 More docs.
193 // All done!
36cf5074 »
2012-03-19 More docs.
194 done(success);
148d6ee6 »
2012-03-19 More docs.
195 }, 1000);
196 ```
5be5bf32 »
2012-03-19 More docs.
197
f353857d »
2012-03-20 More docs.
198 ### this.requires / grunt.task.current.requires
199 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.
200
a167b634 »
2012-03-20 More docs.
201 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.
46c8f4ac »
2012-03-20 More docs.
202
f353857d »
2012-03-20 More docs.
203 ```javascript
204 this.requires(taskList)
205 ```
206
7e13cf48 »
2012-03-20 More docs.
207 ### this.name / grunt.task.current.name
3ee85163 »
2012-03-19 More docs.
208 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"`.
6a891d1e »
2012-03-19 More docs.
209
7e13cf48 »
2012-03-20 More docs.
210 ### this.nameArgs / grunt.task.current.nameArgs
3ee85163 »
2012-03-19 More docs.
211 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"`.
6a891d1e »
2012-03-19 More docs.
212
7e13cf48 »
2012-03-20 More docs.
213 ### this.args / grunt.task.current.args
3ee85163 »
2012-03-19 More docs.
214 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.
148d6ee6 »
2012-03-19 More docs.
215
7e13cf48 »
2012-03-20 More docs.
216 ### this.flags / grunt.task.current.flags
3ee85163 »
2012-03-19 More docs.
217 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.
218
f353857d »
2012-03-20 More docs.
219 ### this.errorCount / grunt.task.current.errorCount
220 The number of [log.error](api_log.md) calls that occurred during this task. This can be used to fail a task if errors occurred during the task.
221
7e13cf48 »
2012-03-20 More docs.
222 ### this.extraspaths / grunt.task.current.extraspaths
18e3d037 »
2012-03-19 More docs.
223 TODO: re-evaluate
3ee85163 »
2012-03-19 More docs.
224
225
226 ## Inside Multi Tasks
227
7e13cf48 »
2012-03-20 More docs.
228 ### this.target / grunt.task.current.target
3ee85163 »
2012-03-19 More docs.
229 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"`.
148d6ee6 »
2012-03-19 More docs.
230
7e13cf48 »
2012-03-20 More docs.
231 ### this.data / grunt.task.current.data
3ee85163 »
2012-03-19 More docs.
232 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"`.
148d6ee6 »
2012-03-19 More docs.
233
7e13cf48 »
2012-03-20 More docs.
234 ### this.file / grunt.task.current.file
48a8956f »
2012-03-19 More docs.
235 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`.
148d6ee6 »
2012-03-19 More docs.
236
5870cd6b »
2012-03-19 More docs.
237 Note that while grunt supports expanding [templates](api_template.md) for both `src` and `dest`, they only work for the `dest` file path when the _full_ format is used.
6a891d1e »
2012-03-19 More docs.
238
18e3d037 »
2012-03-19 More docs.
239 ```javascript
240 grunt.initConfig({
241 concat: {
242 // This is the "compact" format.
243 'dist/built.js': ['src/file1.js', 'src/file2.js'],
244 // This is the "full" format.
245 built: {
246 src: ['src/file1.js', 'src/file2.js'],
247 dest: 'dist/built.js'
248 }
249 }
250 });
251 ```
5be5bf32 »
2012-03-19 More docs.
252
253
0e2160ef »
2012-03-19 More docs.
254 ## Loading Externally-Defined Tasks
89ccb3eb »
2012-03-20 More docs.
255 _Note that the methods listed below are also available on the [grunt.task](api_task.md) object in addition to the `grunt` object._
5be5bf32 »
2012-03-19 More docs.
256
48bcd441 »
2012-03-19 More docs.
257 ### grunt.loadTasks
b744b4e6 »
2012-03-19 More docs.
258 Load task-related files from the specified directory, relative to the [grunt.js gruntfile](configuring.md). 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.
dbaee9c8 »
2012-03-19 More docs.
259
260 ```javascript
cb7a64a7 »
2012-03-19 More docs.
261 grunt.loadTasks(tasksPath)
dbaee9c8 »
2012-03-19 More docs.
262 ```
263
78099bbb »
2012-03-20 More docs.
264 _This method is an alias for the [grunt.task.loadTasks](api_task.md) method._
dbaee9c8 »
2012-03-19 More docs.
265
cb7a64a7 »
2012-03-19 More docs.
266
267 ### grunt.loadNpmTasks
e03cb7a7 »
2012-03-19 More docs.
268 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.
dbaee9c8 »
2012-03-19 More docs.
269
270 ```javascript
cb7a64a7 »
2012-03-19 More docs.
271 grunt.loadNpmTasks(pluginName)
dbaee9c8 »
2012-03-19 More docs.
272 ```
273
78099bbb »
2012-03-20 More docs.
274 _This method is an alias for the [grunt.task.loadNpmTasks](api_task.md) method._
cb7a64a7 »
2012-03-19 More docs.
275
276
0e2160ef »
2012-03-19 More docs.
277 ## Defining and Executing Helpers
89ccb3eb »
2012-03-20 More docs.
278 _Note that the methods listed below are also available on the [grunt.task](api_task.md) object in addition to the `grunt` object._
dbaee9c8 »
2012-03-19 More docs.
279
48bcd441 »
2012-03-19 More docs.
280 ### grunt.registerHelper
2e59c057 »
2012-03-20 More docs.
281 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.
dbaee9c8 »
2012-03-19 More docs.
282
283 ```javascript
34274e30 »
2012-03-19 More docs.
284 grunt.registerHelper(helperName, helperFunction)
dbaee9c8 »
2012-03-19 More docs.
285 ```
286
b744b4e6 »
2012-03-19 More docs.
287 In this example helper, the numbers `1` and `2` are passed in and the value `3` is returned.
288
289 ```javascript
290 grunt.registerHelper("add_two_nums", function(a, b) {
291 return a + b;
292 });
293 ```
294
78099bbb »
2012-03-20 More docs.
295 _This method is an alias for the [grunt.task.registerHelper](api_task.md) method._
296
297 ### grunt.renameHelper
298 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).
299
300 ```javascript
301 grunt.renameHelper(oldname, newname)
302 ```
b744b4e6 »
2012-03-19 More docs.
303
78099bbb »
2012-03-20 More docs.
304 _This method is an alias for the [grunt.task.renameHelper](api_task.md) method._
dbaee9c8 »
2012-03-19 More docs.
305
b744b4e6 »
2012-03-19 More docs.
306 ### grunt.helper
307 Invoke a registered helper function.
dbaee9c8 »
2012-03-19 More docs.
308
309 ```javascript
34274e30 »
2012-03-19 More docs.
310 grunt.helper(helperName [, arguments...])
dbaee9c8 »
2012-03-19 More docs.
311 ```
7ee61b69 »
2012-02-04 Docs reorganization.
312
b744b4e6 »
2012-03-19 More docs.
313 In this example, the previously defined `add_two_nums` helper is invoked.
b260167c »
2012-03-19 More docs.
314
b744b4e6 »
2012-03-19 More docs.
315 ```javascript
316 grunt.helper("add_two_nums", 1, 2) // 3
317 ```
b260167c »
2012-03-19 More docs.
318
78099bbb »
2012-03-20 More docs.
319 _This method is an alias for the [grunt.task.helper](api_task.md) method._
b260167c »
2012-03-19 More docs.
320
321
7ee61b69 »
2012-02-04 Docs reorganization.
322 ## Internals
323
6f02aa23 »
2012-03-19 More docs.
324 * [grunt.utils](api_utils.md) - Miscellaneous utilities, including Underscore.js, Async and Hooker.
51393d86 »
2012-03-20 More docs.
325 * [grunt.template](api_template.md) - Underscore.js template processing and other template-related methods.
62a362fd »
2012-03-19 More docs.
326 * [grunt.task](api_task.md) - The entire task interface
327 * [grunt.file](api_file.md) - Glob expansion, file reading, writing, directory traversing.
328 * [grunt.fail](api_fail.md) - More serious than error logging, `fail.warn` and `fail.fatal` will halt everything
329 * [grunt.config](api_config.md) - Reading values from the grunt configuration.
330 * [grunt.option](api_option.md) - Reading values from the command-line options.
331 * [grunt.log](api_log.md) - Don't use `console.log`, use `log.writeln` instead!
332 * [grunt.verbose](api_verbose.md) - Just like `log`, but only logs if `--verbose` was specified.
7ee61b69 »
2012-02-04 Docs reorganization.
333
334 Unfortunately, I haven't documented everything yet. Fortunately, the source is open and browsable. Have fun!
Something went wrong with that request. Please try again.