This section is a work in progress. Grunt currently has preliminary plugin support, but it might be a little while before plugins work perfectly. If you have any suggestions or comments, please file an issue and we'll work it all out!
Why create a grunt plugin?
Publishing a "grunt plugin" to Npm gives you 3 possible things:
- An easily-included-in-your-project set of tasks that get referenced in
grunt.jswhen run via
- A custom global binary that is like "some version of grunt, plus your specific extra stuff."
- Either 1 or 2, depending on whether the plugin was installed globally or locally via Npm.
Other than that, it's not too much more than a specific directory structure, contain some number of task files. You load a plugin locally installed via Npm via grunt.loadNpmTasks, and you load tasks from a directory via grunt.loadTasks.
Plugin creation and development
grunt init:gruntpluginin an empty directory.
npm installto install grunt locally.
./node_modules/.bin/gruntto run the plugin-specific grunt. Just
- When done, run
npm publishto publish the grunt plugin to npm!
Two usage options
1. Global install, where you run
npm install -g grunt-yourplugin. This installs the plugin globally, which contains its own internal grunt (the version specified in the plugin's package.json).
- A new
grunt-yourpluginbinary should be globally available.
- When run from that binary, the internal grunt runs, and provides grunt's internal tasks and helpers plus all the plugin's tasks and helpers.
- When executed via the plugin binary, eg.
grunt-yourplugin, the internally-specified grunt will be used. This allows you to "lock in" a specific version of grunt to your plugin.
2. Local install, where you run
- Grunt should already have been installed globally with
npm install -g grunt.
- In your project's root, next to the grunt.js gruntfile, run
npm install grunt-yourplugin.
- Add grunt.loadNpmTasks('grunt-yourplugin') into the project's grunt.js gruntfile.
gruntand all of the
grunt-yourplugintasks and helpers should be available in addition to those already provided by grunt..
- Multiple plugins, eg.
grunt-anotherplugincan be installed locally via Npm.
- grunt.loadNpmTasks('grunt-yourplugin') should behave exactly the same as grunt.loadTasks('./node_modules/grunt-yourplugin/tasks') does. It's less to type though, which is awesome.
- More docs.