Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 139 lines (103 sloc) 6.783 kB
b38875e @cowboy Updating docs.
authored
1 [Grunt homepage](https://github.com/cowboy/grunt) | [Documentation table of contents](toc.md)
e6e4b09 @cowboy More documentation.
authored
2
140c0e8 @cowboy More docs.
authored
3 # Getting Started
e6e4b09 @cowboy More documentation.
authored
4
a0535fb @cowboy More docs.
authored
5 **If you're starting from scratch, check out the [init task](task_init.md), which will set up a new grunt-based project for you. Even if you don't ultimately use the files that are generated, you can very quickly learn how grunt works.**
dc8db78 @jzaefferer Documentation for init task
jzaefferer authored
6
c3b16ec @cowboy Adding anchors to docs.
authored
7 ## The grunt.js file, aka "gruntfile" <a name="the-grunt-js-file-aka-gruntfile" href="#the-grunt-js-file-aka-gruntfile" title="Link to this section">⚑</a>
2ada036 @cowboy Adding some edited docs. Note that many changes in these disc apply t…
authored
8 Each time grunt is run, it looks in the current directory for a file named `grunt.js`. If this file is not found, grunt continues looking in parent directories until that file is found. This file is typically placed in the root of your project repository, and is a valid JavaScript file comprised of these parts:
e6e4b09 @cowboy More documentation.
authored
9
2ada036 @cowboy Adding some edited docs. Note that many changes in these disc apply t…
authored
10 * Project configuration
11 * Loading grunt plugins or tasks folders
98d482d @cowboy More docs.
authored
12 * Tasks and helpers
e6e4b09 @cowboy More documentation.
authored
13
a0535fb @cowboy More docs.
authored
14 This is an example of a very basic sample `grunt.js` gruntfile that does all three of these things.
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
15
16 ```javascript
48cec61 @cowboy Changed back to module.exports in tasks files/gruntfiles vs exports.c…
authored
17 module.exports = function(grunt) {
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
18
19 // Project configuration.
20 grunt.initConfig({
21 lint: {
22 all: ['grunt.js', 'lib/**/*.js''test/**/*.js']
23 },
24 jshint: {
2615d34 @cowboy Docs tweaks.
authored
25 options: {
26 browser: true
27 }
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
28 }
29 });
30
b2a86d8 @cowboy More docs.
authored
31 // Load tasks from "grunt-sample" grunt plugin installed via Npm.
2615d34 @cowboy Docs tweaks.
authored
32 grunt.loadNpmTasks('grunt-sample');
33
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
34 // Default task.
2615d34 @cowboy Docs tweaks.
authored
35 grunt.registerTask('default', 'lint sample');
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
36
37 };
38 ```
39
c3b16ec @cowboy Adding anchors to docs.
authored
40 ## A Very Important Note <a name="a-very-important-note" href="#a-very-important-note" title="Link to this section">⚑</a>
98d482d @cowboy More docs.
authored
41 Your `grunt.js` gruntfile **must** contain this code, once and **only** once. If it doesn't, grunt won't work. For the sake of brevity, this "wrapper" code has been omitted from all future examples on this page, but it needs to be there. Like in the previous example.
e6e4b09 @cowboy More documentation.
authored
42
43 ```javascript
48cec61 @cowboy Changed back to module.exports in tasks files/gruntfiles vs exports.c…
authored
44 module.exports = function(grunt) {
a0535fb @cowboy More docs.
authored
45 // Your grunt code goes in here.
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
46 };
e6e4b09 @cowboy More documentation.
authored
47 ```
48
c3b16ec @cowboy Adding anchors to docs.
authored
49 ## Project configuration <a name="project-configuration" href="#project-configuration" title="Link to this section">⚑</a>
c973dfa @cowboy More documentation.
authored
50
a0535fb @cowboy More docs.
authored
51 Each grunt task relies on configuration information defined in an object passed to the [grunt.initConfig](api.md) method.
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
52
a0535fb @cowboy More docs.
authored
53 For example, this basic config defines a list of files to be linted when the [lint task](task_lint.md) is run on the command line via `grunt lint`.
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
54
a0535fb @cowboy More docs.
authored
55 ```javascript
56 // Project configuration.
57 grunt.initConfig({
58 lint: {
59 all: ['lib/*.js', 'test/*.js', 'grunt.js']
60 }
61 });
c973dfa @cowboy More documentation.
authored
62 ```
63
8136083 @cowboy More docs.
authored
64 _Note: the [lint task](task_lint.md) is an example of a [multi task](api.md). You can run all targets of any multi task by just specifying the name of the task. In this case, running `grunt lint` would automatically run the `all` target and any others that might exist under `lint` instead of you having to run `grunt lint:all` explicitly._
e6e4b09 @cowboy More documentation.
authored
65
a0535fb @cowboy More docs.
authored
66 In another example, this very simple configuration saved in the root of a [jQuery repository](https://github.com/jquery/jquery) clone allows the jQuery QUnit unit tests to be run via grunt with `grunt qunit`. Note that even though jQuery's unit tests run in grunt doesn't mean they're going to actually pass. QUnit is running headless, after all!
e6e4b09 @cowboy More documentation.
authored
67
68 ```javascript
a0535fb @cowboy More docs.
authored
69 // Project configuration.
70 grunt.initConfig({
71 qunit: {
72 index: ['test/index.html']
73 }
74 });
e6e4b09 @cowboy More documentation.
authored
75 ```
76
a0535fb @cowboy More docs.
authored
77 You can store any arbitrary information inside of the configuration object, and as long as it doesn't conflict with a property one of your tasks is using, it will be ignored. Also, because this is JavaScript and not JSON, you can use any valid JavaScript here. This allows you to programatically generate the configuration object, if necessary.
e6e4b09 @cowboy More documentation.
authored
78
a0535fb @cowboy More docs.
authored
79 See the documentation [table of contents](toc.md) for a list of tasks whose documentation will explain their specific configuration requirements.
2ada036 @cowboy Adding some edited docs. Note that many changes in these disc apply t…
authored
80
a0535fb @cowboy More docs.
authored
81 _Also note that you don't need to specify configuration settings for tasks that you don't use._
2ada036 @cowboy Adding some edited docs. Note that many changes in these disc apply t…
authored
82
83 ```javascript
a0535fb @cowboy More docs.
authored
84 // Project configuration.
85 grunt.initConfig({
86 // Project metadata, used by some directives, helpers and tasks.
87 meta: {},
88 // Lists of files to be concatenated, used by the "concat" task.
89 concat: {},
90 // Lists of files to be linted with JSHint, used by the "lint" task.
91 lint: {},
03814fb @cowboy More docs.
authored
92 // Lists of files to be minified with UglifyJS, used by the "min" task.
a0535fb @cowboy More docs.
authored
93 min: {},
94 // Lists of files or URLs to be unit tested with QUnit, used by the "qunit" task.
95 qunit: {},
96 // Configuration options for the "server" task.
97 server: {},
98 // Lists of files to be unit tested with Nodeunit, used by the "test" task.
99 test: {},
100 // Configuration options for the "watch" task.
101 watch: {},
102 // Global configuration options for JSHint.
103 jshint: {},
104 // Global configuration options for UglifyJS.
105 uglify: {}
106 });
107 ```
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
108
c3b16ec @cowboy Adding anchors to docs.
authored
109 ## Loading grunt plugins or tasks folders <a name="loading-grunt-plugins-or-tasks-folders" href="#loading-grunt-plugins-or-tasks-folders" title="Link to this section">⚑</a>
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
110
8136083 @cowboy More docs.
authored
111 While you can define [tasks and helpers](api.md) in your project's gruntfile, you can also load tasks from external sources.
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
112
a0535fb @cowboy More docs.
authored
113 ```javascript
114 // Load tasks and helpers from the "tasks" directory, relative to grunt.js.
115 grunt.loadTasks('tasks');
116
8136083 @cowboy More docs.
authored
117 // Load tasks and helpers from the "grunt-sample" Npm-installed grunt plugin.
a0535fb @cowboy More docs.
authored
118 grunt.loadNpmTasks('grunt-sample');
2ada036 @cowboy Adding some edited docs. Note that many changes in these disc apply t…
authored
119 ```
120
a0535fb @cowboy More docs.
authored
121 _Note: loading externally defined tasks and helpers in this way is preferred to loading them via the analogous `--tasks` and `--npm` command-line options. This is because when tasks are created or loaded in the `grunt.js` gruntfile, the tasks effectively become part of the project and will always be used (provided they are available) whenever `grunt` is run._
2ada036 @cowboy Adding some edited docs. Note that many changes in these disc apply t…
authored
122
c3b16ec @cowboy Adding anchors to docs.
authored
123 ## Tasks and helpers <a name="tasks-and-helpers" href="#tasks-and-helpers" title="Link to this section">⚑</a>
4f97f45 @cowboy More documentation.
authored
124
a0535fb @cowboy More docs.
authored
125 You aren't required to define tasks in your project gruntfile, because grunt provides a number of built-in tasks. That being said, until you define a `default` task, grunt won't know what to do when you run it just as `grunt` without specifying any tasks, because grunt doesn't provide a default `default` task.
4f97f45 @cowboy More documentation.
authored
126
a0535fb @cowboy More docs.
authored
127 The easiest way to define the default task is to create an [alias task](api.md).
4f97f45 @cowboy More documentation.
authored
128
2ada036 @cowboy Adding some edited docs. Note that many changes in these disc apply t…
authored
129 In the following example, a default task is defined that, when invoked by specifying `grunt` or `grunt default` on the command line, will execute the `lint`, `qunit`, `concat` and `min` tasks in-order. It behaves exactly as if `grunt lint qunit concat min` was run on the command line.
4f97f45 @cowboy More documentation.
authored
130
131 ```javascript
a0535fb @cowboy More docs.
authored
132 // Default task.
c2b56c0 @cowboy Fixing a few documentation typos.
authored
133 grunt.registerTask('default', 'lint qunit concat min');
4f97f45 @cowboy More documentation.
authored
134 ```
135
c801502 @cowboy Updating configuration docs to reflect the updated API.
authored
136 _Note: choose the default tasks that make the most sense for your project. If you find yourself commonly executing other groups of tasks, create as many named aliases as you need!_
4f97f45 @cowboy More documentation.
authored
137
a0535fb @cowboy More docs.
authored
138 Take a look at the [example gruntfiles](example_gruntfiles.md) or check out the [init task](task_init.md) for more configuration examples.
Something went wrong with that request. Please try again.