Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 304 lines (206 sloc) 11.928 kb
7ee61b6 @cowboy Docs reorganization.
authored
1 [Grunt homepage](https://github.com/cowboy/grunt) | [Documentation table of contents](toc.md)
2
3 # The grunt API
4
82a6799 @cowboy More docs.
authored
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).
dbaee9c @cowboy More docs.
authored
6
82a6799 @cowboy More docs.
authored
7 For example, your project's [grunt.js gruntfile](configuring.md) might look like this:
dbaee9c @cowboy More docs.
authored
8
9 ```javascript
10 exports.config = function(grunt) {
ee1939e @cowboy More docs.
authored
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
b2a86d8 @cowboy More docs.
authored
24 // Load tasks from "grunt-sample" grunt plugin installed via Npm.
ee1939e @cowboy More docs.
authored
25 grunt.loadNpmTasks('grunt-sample');
26
27 // Default task.
28 grunt.registerTask('default', 'lint sample');
29
dbaee9c @cowboy More docs.
authored
30 };
31 ```
32
c8e22b4 @cowboy More docs.
authored
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:
dbaee9c @cowboy More docs.
authored
34
35 ```javascript
36 exports.tasks = function(grunt) {
ee1939e @cowboy More docs.
authored
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
dbaee9c @cowboy More docs.
authored
49 };
50 ```
51
16c967b @cowboy More docs.
authored
52 But these are just examples. For more information, take a look at the API documentation:
5b73737 @cowboy More docs.
authored
53
48bcd44 @cowboy More docs.
authored
54 ## Config
dbaee9c @cowboy More docs.
authored
55
80581c2 @cowboy More docs.
authored
56
48bcd44 @cowboy More docs.
authored
57 ### grunt.initConfig
82a6799 @cowboy More docs.
authored
58 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.
dbaee9c @cowboy More docs.
authored
59
60 ```javascript
34274e3 @cowboy More docs.
authored
61 grunt.initConfig(configObject)
62 ```
63
31950dd @cowboy More docs.
authored
64 This example contains sample config data for the [lint task](task_lint.md):
34274e3 @cowboy More docs.
authored
65
66 ```javascript
67 grunt.initConfig({
68 lint: {
69 all: ['lib/*.js', 'test/*.js', 'grunt.js']
70 }
71 });
dbaee9c @cowboy More docs.
authored
72 ```
73
5a41466 @cowboy More docs.
authored
74 See the [configuring grunt](configuring.md) page for more configuration examples.
29b12b9 @cowboy More docs.
authored
75
fbc0986 @cowboy More docs.
authored
76 _This method is an alias for the [config.init](api_config.md) method._
dbaee9c @cowboy More docs.
authored
77
48bcd44 @cowboy More docs.
authored
78
0e2160e @cowboy More docs.
authored
79 ## Creating Tasks
48bcd44 @cowboy More docs.
authored
80
80581c2 @cowboy More docs.
authored
81
48bcd44 @cowboy More docs.
authored
82 ### grunt.registerTask
e2bebb6 @cowboy More docs.
authored
83 Register an "alias task" or a task function. This method supports the following two signatures:
dbaee9c @cowboy More docs.
authored
84
cc08918 @cowboy More docs.
authored
85 **Alias task**
5c46902 @cowboy More docs.
authored
86
80581c2 @cowboy More docs.
authored
87 If a string `taskList` 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.
dbaee9c @cowboy More docs.
authored
88
89 ```javascript
34274e3 @cowboy More docs.
authored
90 grunt.registerTask(taskName, taskList)
f531113 @cowboy More docs.
authored
91 ```
92
e2bebb6 @cowboy More docs.
authored
93 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:
94
95 ```javascript
96 task.registerTask('default', 'lint qunit concat min');
97 ```
98
cc08918 @cowboy More docs.
authored
99 **Function task**
5c46902 @cowboy More docs.
authored
100
80581c2 @cowboy More docs.
authored
101 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.
102
103 Note that the `grunt.registerMultiTask` method, explained below, can be used to define a special type of task known as a "multi task."
f531113 @cowboy More docs.
authored
104
105 ```javascript
34274e3 @cowboy More docs.
authored
106 grunt.registerTask(taskName, description, taskFunction)
dbaee9c @cowboy More docs.
authored
107 ```
108
451428f @cowboy More docs.
authored
109 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`.
5dacc94 @cowboy More docs.
authored
110
111 ```javascript
112 grunt.registerTask('foo', 'A sample task that logs stuff.', function(arg1, arg2) {
113 if (arguments.length === 0) {
114 grunt.log.writeln(this.name + ", no args");
115 } else {
116 grunt.log.writeln(this.name + ", " + arg1 + " " + arg2);
117 }
118 });
119 ```
120
82a6799 @cowboy More docs.
authored
121 See the [creating tasks](tasks_creating.md) documentation for more examples of tasks and alias tasks.
f531113 @cowboy More docs.
authored
122
fbc0986 @cowboy More docs.
authored
123 _This method is an alias for the [task.registerTask](api_task.md) method._
f531113 @cowboy More docs.
authored
124
125
48bcd44 @cowboy More docs.
authored
126 ### grunt.registerMultiTask
451428f @cowboy More docs.
authored
127 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.
dbaee9c @cowboy More docs.
authored
128
31950dd @cowboy More docs.
authored
129 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.
dbaee9c @cowboy More docs.
authored
130
131 ```javascript
34274e3 @cowboy More docs.
authored
132 grunt.registerMultiTask(taskName, description, taskFunction)
dbaee9c @cowboy More docs.
authored
133 ```
134
82a6799 @cowboy More docs.
authored
135 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`.
451428f @cowboy More docs.
authored
136
137 ```javascript
138 grunt.initConfig({
139 log: {
140 foo: [1, 2, 3],
141 bar: 'hello world',
142 baz: false
143 }
144 });
145
146 grunt.registerMultiTask('log', 'Log stuff.', function(target) {
147 grunt.log.writeln(target + ': ' + this.data);
148 });
149 ```
150
82a6799 @cowboy More docs.
authored
151 See the [creating tasks](tasks_creating.md) documentation for more examples of multi tasks.
80581c2 @cowboy More docs.
authored
152
153 _This method is an alias for the [task.registerMultiTask](api_task.md) method._
154
155
48bcd44 @cowboy More docs.
authored
156 ### grunt.registerInitTask
fd45238 @cowboy More docs.
authored
157 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.
dbaee9c @cowboy More docs.
authored
158
159 ```javascript
34274e3 @cowboy More docs.
authored
160 grunt.registerInitTask(taskName, description, taskFunction)
dbaee9c @cowboy More docs.
authored
161 ```
162
fd45238 @cowboy More docs.
authored
163 For an init task example, see the [init task source](../tasks/init.js).
82a6799 @cowboy More docs.
authored
164
5be5bf3 @cowboy More docs.
authored
165 _This method is an alias for the [task.registerInitTask](api_task.md) method._
166
167
18e3d03 @cowboy More docs.
authored
168 ## Inside Tasks
5be5bf3 @cowboy More docs.
authored
169
29a06f8 @cowboy More docs.
authored
170 ### this / grunt.task.current
171 This object is available inside each task as `this` while it runs, and contains a number of useful task-specific properties and methods. It is also exposed as `grunt.task.current` for external use (for example, in templates).
172
7e13cf4 @cowboy More docs.
authored
173 ### this.async / grunt.task.current.async
62a16c0 @cowboy More docs.
authored
174 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.
148d6ee @cowboy More docs.
authored
175
176 ```javascript
177 // Tell grunt this task is asynchronous.
178 var done = this.async();
179 // Your async code.
180 setTimeout(function() {
d5405a4 @cowboy More docs.
authored
181 // Let's simulate an error, sometimes.
36cf507 @cowboy More docs.
authored
182 var success = Math.random() > 0.5;
62a16c0 @cowboy More docs.
authored
183 // All done!
36cf507 @cowboy More docs.
authored
184 done(success);
148d6ee @cowboy More docs.
authored
185 }, 1000);
186 ```
5be5bf3 @cowboy More docs.
authored
187
7e13cf4 @cowboy More docs.
authored
188 ### this.name / grunt.task.current.name
3ee8516 @cowboy More docs.
authored
189 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"`.
6a891d1 @cowboy More docs.
authored
190
7e13cf4 @cowboy More docs.
authored
191 ### this.nameArgs / grunt.task.current.nameArgs
3ee8516 @cowboy More docs.
authored
192 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"`.
6a891d1 @cowboy More docs.
authored
193
7e13cf4 @cowboy More docs.
authored
194 ### this.args / grunt.task.current.args
3ee8516 @cowboy More docs.
authored
195 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.
148d6ee @cowboy More docs.
authored
196
7e13cf4 @cowboy More docs.
authored
197 ### this.flags / grunt.task.current.flags
3ee8516 @cowboy More docs.
authored
198 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.
199
7e13cf4 @cowboy More docs.
authored
200 ### this.extraspaths / grunt.task.current.extraspaths
18e3d03 @cowboy More docs.
authored
201 TODO: re-evaluate
3ee8516 @cowboy More docs.
authored
202
203
204 ## Inside Multi Tasks
205
7e13cf4 @cowboy More docs.
authored
206 ### this.target / grunt.task.current.target
3ee8516 @cowboy More docs.
authored
207 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"`.
148d6ee @cowboy More docs.
authored
208
7e13cf4 @cowboy More docs.
authored
209 ### this.data / grunt.task.current.data
3ee8516 @cowboy More docs.
authored
210 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"`.
148d6ee @cowboy More docs.
authored
211
7e13cf4 @cowboy More docs.
authored
212 ### this.file / grunt.task.current.file
48a8956 @cowboy More docs.
authored
213 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`.
148d6ee @cowboy More docs.
authored
214
5870cd6 @cowboy More docs.
authored
215 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.
6a891d1 @cowboy More docs.
authored
216
18e3d03 @cowboy More docs.
authored
217 ```javascript
218 grunt.initConfig({
219 concat: {
220 // This is the "compact" format.
221 'dist/built.js': ['src/file1.js', 'src/file2.js'],
222 // This is the "full" format.
223 built: {
224 src: ['src/file1.js', 'src/file2.js'],
225 dest: 'dist/built.js'
226 }
227 }
228 });
229 ```
5be5bf3 @cowboy More docs.
authored
230
231
0e2160e @cowboy More docs.
authored
232 ## Loading Externally-Defined Tasks
dbaee9c @cowboy More docs.
authored
233
5be5bf3 @cowboy More docs.
authored
234
48bcd44 @cowboy More docs.
authored
235 ### grunt.loadTasks
b744b4e @cowboy More docs.
authored
236 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.
dbaee9c @cowboy More docs.
authored
237
238 ```javascript
cb7a64a @cowboy More docs.
authored
239 grunt.loadTasks(tasksPath)
dbaee9c @cowboy More docs.
authored
240 ```
241
cb7a64a @cowboy More docs.
authored
242 _This method is an alias for the [task.loadTasks](api_task.md) method._
dbaee9c @cowboy More docs.
authored
243
cb7a64a @cowboy More docs.
authored
244
245 ### grunt.loadNpmTasks
e03cb7a @cowboy More docs.
authored
246 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.
dbaee9c @cowboy More docs.
authored
247
248 ```javascript
cb7a64a @cowboy More docs.
authored
249 grunt.loadNpmTasks(pluginName)
dbaee9c @cowboy More docs.
authored
250 ```
251
cb7a64a @cowboy More docs.
authored
252 _This method is an alias for the [task.loadNpmTasks](api_task.md) method._
253
254
0e2160e @cowboy More docs.
authored
255 ## Defining and Executing Helpers
dbaee9c @cowboy More docs.
authored
256
48bcd44 @cowboy More docs.
authored
257 ### grunt.registerHelper
b744b4e @cowboy More docs.
authored
258 Register a helper function that can be used by any task.
dbaee9c @cowboy More docs.
authored
259
260 ```javascript
34274e3 @cowboy More docs.
authored
261 grunt.registerHelper(helperName, helperFunction)
dbaee9c @cowboy More docs.
authored
262 ```
263
b744b4e @cowboy More docs.
authored
264 In this example helper, the numbers `1` and `2` are passed in and the value `3` is returned.
265
266 ```javascript
267 grunt.registerHelper("add_two_nums", function(a, b) {
268 return a + b;
269 });
270 ```
271
272 _This method is an alias for the [task.registerHelper](api_task.md) method._
273
dbaee9c @cowboy More docs.
authored
274
b744b4e @cowboy More docs.
authored
275 ### grunt.helper
276 Invoke a registered helper function.
dbaee9c @cowboy More docs.
authored
277
278 ```javascript
34274e3 @cowboy More docs.
authored
279 grunt.helper(helperName [, arguments...])
dbaee9c @cowboy More docs.
authored
280 ```
7ee61b6 @cowboy Docs reorganization.
authored
281
b744b4e @cowboy More docs.
authored
282 In this example, the previously defined `add_two_nums` helper is invoked.
b260167 @cowboy More docs.
authored
283
b744b4e @cowboy More docs.
authored
284 ```javascript
285 grunt.helper("add_two_nums", 1, 2) // 3
286 ```
b260167 @cowboy More docs.
authored
287
b744b4e @cowboy More docs.
authored
288 _This method is an alias for the [task.helper](api_task.md) method._
b260167 @cowboy More docs.
authored
289
290
7ee61b6 @cowboy Docs reorganization.
authored
291 ## Internals
292
6f02aa2 @cowboy More docs.
authored
293 * [grunt.utils](api_utils.md) - Miscellaneous utilities, including Underscore.js, Async and Hooker.
51393d8 @cowboy More docs.
authored
294 * [grunt.template](api_template.md) - Underscore.js template processing and other template-related methods.
62a362f @cowboy More docs.
authored
295 * [grunt.task](api_task.md) - The entire task interface
296 * [grunt.file](api_file.md) - Glob expansion, file reading, writing, directory traversing.
297 * [grunt.fail](api_fail.md) - More serious than error logging, `fail.warn` and `fail.fatal` will halt everything
298 * [grunt.config](api_config.md) - Reading values from the grunt configuration.
299 * [grunt.option](api_option.md) - Reading values from the command-line options.
300 * [grunt.log](api_log.md) - Don't use `console.log`, use `log.writeln` instead!
301 * [grunt.verbose](api_verbose.md) - Just like `log`, but only logs if `--verbose` was specified.
7ee61b6 @cowboy Docs reorganization.
authored
302
303 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.