0
# Load Grunt Tasks
1

2
Load multiple grunt tasks using globbing patterns. This package eliminates the need to manually load each grunt task plugin individually by reading dependencies from package.json and automatically loading tasks that match specified patterns.
3

4
## Package Information
5

6
- **Package Name**: load-grunt-tasks
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev load-grunt-tasks`
10

11
## Core Imports
12

13
```javascript
14
const loadGruntTasks = require('load-grunt-tasks');
15
```
16

17
## Basic Usage
18

19
```javascript
20
// Gruntfile.js
21
module.exports = grunt => {
22
    // Load all grunt tasks matching the ['grunt-*', '@*/grunt-*'] patterns
23
    require('load-grunt-tasks')(grunt);
24

25
    grunt.initConfig({
26
        // Your task configurations
27
    });
28
    
29
    grunt.registerTask('default', ['your-tasks']);
30
};
31
```
32

33
## Capabilities
34

35
### Main Function
36

37
Loads multiple grunt tasks automatically using globbing patterns based on package.json dependencies.
38

39
```javascript { .api }
40
/**
41
 * Load multiple grunt tasks using globbing patterns
42
 * @param {Object} grunt - The grunt instance to load tasks into
43
 * @param {Object} options - Configuration options for task loading behavior
44
 * @returns {undefined} - Function has side effects (loads tasks into grunt) but returns nothing
45
 */
46
function loadGruntTasks(grunt, options);
47
```
48

49
**Usage Examples:**
50

51
```javascript
52
// Load all grunt tasks (default behavior)
53
require('load-grunt-tasks')(grunt);
54

55
// Load only grunt-contrib tasks
56
require('load-grunt-tasks')(grunt, {
57
    pattern: 'grunt-contrib-*'
58
});
59

60
// Load from specific dependency types only
61
require('load-grunt-tasks')(grunt, {
62
    scope: ['devDependencies']
63
});
64

65
// Load with custom package.json path
66
require('load-grunt-tasks')(grunt, {
67
    config: '../package.json'
68
});
69

70
// Enable require resolution for traversal
71
require('load-grunt-tasks')(grunt, {
72
    requireResolution: true
73
});
74

75
// All options combined
76
require('load-grunt-tasks')(grunt, {
77
    pattern: ['grunt-contrib-*', 'grunt-shell'],
78
    config: '../package.json',
79
    scope: ['devDependencies', 'dependencies'],
80
    requireResolution: true
81
});
82
```
83

84
### Configuration Options
85

86
The options object supports the following properties:
87

88
```javascript { .api }
89
/**
90
 * Configuration options for load-grunt-tasks
91
 */
92
interface Options {
93
    /** Glob patterns to match package names for task loading */
94
    pattern?: string | string[];
95
    /** Package.json dependency sections to search for grunt tasks */
96
    scope?: string | string[];
97
    /** Path to package.json file or package.json object to read dependencies from */
98
    config?: string | object;
99
    /** Whether to traverse up file hierarchy looking for dependencies using require() resolution */
100
    requireResolution?: boolean;
101
}
102
```
103

104
#### pattern
105

106
**Type**: `string | string[]`  
107
**Default**: `['grunt-*', '@*/grunt-*']`
108

109
Glob patterns to match package names for task loading. Supports negative patterns using `!` prefix.
110

111
```javascript
112
// Single pattern
113
require('load-grunt-tasks')(grunt, {
114
    pattern: 'grunt-contrib-*'
115
});
116

117
// Multiple patterns
118
require('load-grunt-tasks')(grunt, {
119
    pattern: ['grunt-contrib-*', 'grunt-shell']
120
});
121

122
// Exclude specific tasks
123
require('load-grunt-tasks')(grunt, {
124
    pattern: ['grunt-contrib-*', '!grunt-contrib-coffee']
125
});
126
```
127

128
#### scope
129

130
**Type**: `string | string[]`  
131
**Default**: `['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']`
132

133
Package.json dependency sections to search for grunt tasks. Handles both npm-style dependency objects and array formats automatically.
134

135
**Valid values**: `'dependencies'`, `'devDependencies'`, `'peerDependencies'`, `'optionalDependencies'`, `'bundledDependencies'`
136

137
```javascript
138
// Load only from devDependencies
139
require('load-grunt-tasks')(grunt, {
140
    scope: 'devDependencies'
141
});
142

143
// Load from multiple scopes
144
require('load-grunt-tasks')(grunt, {
145
    scope: ['devDependencies', 'dependencies']
146
});
147
```
148

149
#### config
150

151
**Type**: `string | object`  
152
**Default**: Path to nearest package.json (found using pkg-up)
153

154
Path to package.json file or package.json object to read dependencies from. When a string path is provided, the working directory is updated to the directory containing that package.json file (affects `requireResolution` behavior).
155

156
```javascript
157
// Custom path to package.json
158
require('load-grunt-tasks')(grunt, {
159
    config: '../package.json'
160
});
161

162
// Pass package.json object directly
163
const packageJson = require('./package.json');
164
require('load-grunt-tasks')(grunt, {
165
    config: packageJson
166
});
167
```
168

169
#### requireResolution
170

171
**Type**: `boolean`  
172
**Default**: `false`
173

174
Whether to traverse up the file hierarchy looking for dependencies using require() resolution, rather than the default grunt-like behavior of loading tasks only in the immediate `node_modules` directory. When enabled, uses `grunt.loadTasks()` with resolved paths instead of `grunt.loadNpmTasks()`.
175

176
```javascript
177
// Enable require resolution (uses grunt.loadTasks with path resolution)
178
require('load-grunt-tasks')(grunt, {
179
    requireResolution: true
180
});
181

182
// Default behavior (uses grunt.loadNpmTasks)
183
require('load-grunt-tasks')(grunt, {
184
    requireResolution: false
185
});
186
```
187

188
## Error Handling
189

190
The function handles errors as follows:
191

192
- **Fatal Error**: Throws a fatal error if no package.json is found when config is not provided
193
- **Non-fatal Errors**: Logs error messages for packages that cannot be found when `requireResolution: true` is used
194

195
```javascript
196
// This will throw a fatal error if no package.json is found
197
require('load-grunt-tasks')(grunt);
198

199
// This will log errors for missing packages but continue execution
200
require('load-grunt-tasks')(grunt, {
201
    requireResolution: true
202
});
203
```
204

205
## Behavior Notes
206

207
- Automatically excludes 'grunt' and 'grunt-cli' packages to prevent conflicts
208
- Supports both scoped (`@scope/grunt-*`) and unscoped (`grunt-*`) npm packages
209
- Uses `grunt.loadNpmTasks()` by default or `grunt.loadTasks()` with resolution when `requireResolution: true`
210
- Processes dependencies synchronously
211
- Integrates seamlessly with Grunt's native task loading system