Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 267 lines (176 sloc) 8.788 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
168 ## Inside Tasks
169
148d6ee @cowboy More docs.
authored
170 ### this.async
62a16c0 @cowboy More docs.
authored
171 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
172
173 ```javascript
174 // Tell grunt this task is asynchronous.
175 var done = this.async();
176 // Your async code.
177 setTimeout(function() {
62a16c0 @cowboy More docs.
authored
178 // Let's simulate an error.. sometimes.
36cf507 @cowboy More docs.
authored
179 var success = Math.random() > 0.5;
62a16c0 @cowboy More docs.
authored
180 // All done!
36cf507 @cowboy More docs.
authored
181 done(success);
148d6ee @cowboy More docs.
authored
182 }, 1000);
183 ```
5be5bf3 @cowboy More docs.
authored
184
6a891d1 @cowboy More docs.
authored
185 ### this.name
2e6d2f7 @cowboy More docs.
authored
186 The name of the task, as-specified in `grunt.registerTask`. For example, if the [min task](task_min.md) was run as `grunt min` or `grunt min:foo`, inside the task function, `this.name === "min"`.
6a891d1 @cowboy More docs.
authored
187
188 ### this.nameArgs
148d6ee @cowboy More docs.
authored
189 The name of the task, as-specified with any colon-separated arguments or flags on the command-line. For example, if the [min task](task_min.md) was run as `grunt min:foo`, inside the task function, `this.nameArgs === "min:foo"`.
6a891d1 @cowboy More docs.
authored
190
148d6ee @cowboy More docs.
authored
191 ### this.args
192
193 ### this.flags
194
195 ### this.data
196
197 ### this.file
198
199 ### this.extraspaths
6a891d1 @cowboy More docs.
authored
200
5be5bf3 @cowboy More docs.
authored
201
202
0e2160e @cowboy More docs.
authored
203 ## Loading Externally-Defined Tasks
dbaee9c @cowboy More docs.
authored
204
5be5bf3 @cowboy More docs.
authored
205
48bcd44 @cowboy More docs.
authored
206 ### grunt.loadTasks
fbc0986 @cowboy More docs.
authored
207 This method is an alias for the [task.loadTasks](api_task.md) method.
dbaee9c @cowboy More docs.
authored
208
209 Usage:
210
211 ```javascript
34274e3 @cowboy More docs.
authored
212 grunt.loadTasks()
dbaee9c @cowboy More docs.
authored
213 ```
214
48bcd44 @cowboy More docs.
authored
215 ### grunt.loadNpmTasks
fbc0986 @cowboy More docs.
authored
216 This method is an alias for the [task.loadNpmTasks](api_task.md) method.
dbaee9c @cowboy More docs.
authored
217
218 Usage:
219
220 ```javascript
34274e3 @cowboy More docs.
authored
221 grunt.loadNpmTasks()
dbaee9c @cowboy More docs.
authored
222 ```
223
0e2160e @cowboy More docs.
authored
224 ## Defining and Executing Helpers
dbaee9c @cowboy More docs.
authored
225
48bcd44 @cowboy More docs.
authored
226 ### grunt.registerHelper
fbc0986 @cowboy More docs.
authored
227 This method is an alias for the [task.registerHelper](api_task.md) method.
dbaee9c @cowboy More docs.
authored
228
229 Usage:
230
231 ```javascript
34274e3 @cowboy More docs.
authored
232 grunt.registerHelper(helperName, helperFunction)
dbaee9c @cowboy More docs.
authored
233 ```
234
48bcd44 @cowboy More docs.
authored
235 ### grunt.helper
fbc0986 @cowboy More docs.
authored
236 This method is an alias for the [task.helper](api_task.md) method.
dbaee9c @cowboy More docs.
authored
237
238 Usage:
239
240 ```javascript
34274e3 @cowboy More docs.
authored
241 grunt.helper(helperName [, arguments...])
dbaee9c @cowboy More docs.
authored
242 ```
7ee61b6 @cowboy Docs reorganization.
authored
243
b260167 @cowboy More docs.
authored
244
245
246
247
7ee61b6 @cowboy Docs reorganization.
authored
248 ## Internals
249
dbaee9c @cowboy More docs.
authored
250 * [grunt.utils](api_utils.md) - miscellaneous utilities
251 * [grunt.template](api_template.md) - template methods
252 * [grunt.task](api_task.md) - the entire task interface
253 * [grunt.file](api_file.md) - glob expansion, file reading, writing, directory traversing
254 * [grunt.fail](api_fail.md) - more serious than error logging, `fail.warn` and `fail.fatal` will halt everything
255 * [grunt.config](api_config.md) - reading values from the grunt configuration
256 * [grunt.option](api_option.md) - reading values from the command-line options
257 * [grunt.log](api_log.md) - don't use `console.log`, use `log.writeln` instead!
258 * [grunt.verbose](api_verbose.md) - just like `log`, but only logs if `--verbose` was specified.
7ee61b6 @cowboy Docs reorganization.
authored
259
392aef1 @cowboy Removing globals "underscore" and "async" which are now available as …
authored
260 ## External libraries, exposed
261
dbaee9c @cowboy More docs.
authored
262 * [utils.async](api_utils.md) - [Async utilities](https://github.com/caolan/async)
263 * [utils._](api_utils.md) - [Underscore.js](http://underscorejs.org/), including [Underscore.string](https://github.com/epeli/underscore.string)
264 * [utils.hooker](api_utils.md) - [JavaScript hooker](https://github.com/cowboy/javascript-hooker)
392aef1 @cowboy Removing globals "underscore" and "async" which are now available as …
authored
265
7ee61b6 @cowboy Docs reorganization.
authored
266 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.