Note that even if you are familiar with grunt, it would be worthwhile to read the new Getting started guide.
Grunt is now split into three parts: grunt
, grunt-cli
and grunt-init
.
grunt
should be installed locally to your project. It contains the code and logic for running tasks, loading plugins, etc.grunt-cli
should be installed globally. It puts the grunt
command in your PATH so you can execute it anywhere. By itself, it doesn't do anything; its job is to load and run the Grunt that has been installed locally to your project, regardless of the version. For more information about why this has changed, please read npm 1.0: Global vs Local installation.init
task has been broken into its own npm module, grunt-init
. It should be installed globally with npm install -g grunt-init
and run with the grunt-init
command. In the coming months, Yeoman will completely replace grunt-init. See the grunt-init project page for more information.If you are upgrading from Grunt 0.3, make sure to uninstall global grunt
:
npm uninstall -g grunt
Note that for 0.3.x, plugin names and task configuration options may be different than those shown in "The Gruntfile" section.
This file was named grunt.js
for 0.3.x versions of Grunt.
All grunt-contrib-*
series plugins are Grunt 0.4 ready. However, it is highly unlikely that third party plugins written for Grunt 0.3 will continue to work with 0.4 until they have been updated. We are actively working with plugin authors to ensure this happens as swiftly as possible.
A forthcoming Grunt release will be focused on decoupling grunt's architecture so that plugins are not affected by future updates.
>= 0.8.0
grunt.js
to Gruntfile.js
.Gruntfile.coffee
project Gruntfile
or *.coffee
task files (transpiling to JS happens automatically).See the "The Gruntfile" section of the Getting started guide for more information.
The eight core tasks that were included in Grunt 0.3 are now separate Grunt plugins. Each is a discrete npm module that must be installed as a plugin per the "Loading Grunt plugins and tasks" section of the Getting started guide.
Some task names and options have changed. Be sure to see each plugin's documentation as linked above for the latest configuration details.
The configuration format for Grunt 0.4 tasks has been standardized and greatly enhanced. See the Configuring tasks guide, as well as individual plugin documentation for more information.
options
object.files
object.<% %>
style template strings specified as config data inside the Gruntfile
are automatically expanded, see the grunt.template documentation for more information.
Directives have been removed, but their functionality has been retained. These replacements can be made:
'<config:prop.subprop>'
→ '<%= prop.subprop %>'
'<json:file.json>'
→ grunt.file.readJSON('file.json')
'<file_template:file.js>'
→ grunt.template.process(grunt.file.read('file.js'))
Instead of specifying a banner in a file list with '<banner>'
or '<banner:prop.subprop>'
, the grunt-contrib-concat and grunt-contrib-uglify plugins each have a banner
option.
Instead of stripping banners from files individually with '<file_strip_banner:file.js>'
, the grunt-contrib-concat and grunt-contrib-uglify plugins each have an option to strip/preserve banners.
When specifying an alias task, the list of tasks to run must now be specified as an array.
// v0.3.x (old format) grunt.registerTask('default', 'jshint nodeunit concat'); // v0.4.x (new format) grunt.registerTask('default', ['jshint', 'nodeunit', 'concat']);
The aforementioned alias task change (task lists must be specified as an array) makes this possible. Just be sure to surround task arguments containing spaces with quotes when specifying them on the command line, so they can be properly parsed.
grunt my-task:argument-without-spaces "other-task:argument with spaces"
The file.defaultEncoding method was added to normalize character encodings, and all grunt.file
methods have been updated to support the specified encoding.
Grunt's helper system has been removed in favor of node require
. For a concise example on how to share functionality between Grunt plugins, please see grunt-lib-legacyhelpers. Plugin authors are encouraged to upgrade their plugins.
The Grunt API saw substantial changes from 0.3 to 0.4.
grunt.registerHelper
and grunt.renameHelper
methods.<% %>
templates.config.get
, but not inside of config.getRaw
.--no-color
option specified.fail.code
exit code map.fail.warnAlternate
method.~/.grunt/tasks/
directory (install them locally to your project!).grunt.file
methods.file.userDir
method (moved into grunt-init).file.clearRequireCache
method.file.expandFiles
and file.expandDirs
methods, use the filter
option of file.expand
instead.file.expandFileURLs
method. Don't specify URLs where files should be specified (eg. the qunit task now allows for a urls
option).this.options
method.files
objects into the this.file
property.task.registerHelper
and task.renameHelper
methods.task.searchDirs
property.task.expand
task.expandDirs
task.expandFiles
task.getFile
task.readDefaults
methods (moved into grunt-init).package.json
.init
and user
template delimiters have been removed, but you can add them in again if you need to with template.addDelimiters
(grunt-init uses this to enable the {% %}
template delimiters).grunt.utils
.util._
to use Lo-Dash
Plugin authors, please indicate clearly on your repository README which version number of your Grunt plugin breaks compatibility with Grunt 0.3.
files
object (this is optional).this.files
property is an array of src-dest file mapping objects to be iterated over in your multi task. It will always be an array, and you should always iterate over it, even if the most common use case is to specify a single file.src
and dest
property (and possibly others, depending on what the user specified). The src
property is already expanded from whatever glob pattern the user may have specified.this.filesSrc
property is a reduced, uniqued array of all files matched by all specified src
properties. Useful for read-only tasks.this.options
method may be used within tasks to normalize options. Inside a task, you may specify options defaults like: var options = this.options({option: 'defaultvalue', ...});
gruntplugin
template has been created for Grunt 0.4-compatible plugins, and is available in the standalone grunt-init.npm cache clean
first to ensure that you are pulling the final version of Grunt and grunt-contrib plugins.
© GruntJS Team
Licensed under the MIT License.
http://gruntjs.com/upgrading-from-0.3-to-0.4