This grunt task iterates over its source files, calculating the MD5 hash of each, then creates a file containing the list of filenames and hashes. This file can then be used in your project to generate filenames that contain the MD5 hash of the file's contents, e.g. main-ae65552d65cd19ab4f1996c77915ed42.js, so that even if a sticky cache is used, clients will always load the latest version of files whenever they change.
This plugin requires Grunt >=0.4.0
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-cachebuster --save-devOne the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-cachebuster');In your project's Gruntfile, add a section named cachebuster to the data object passed into grunt.initConfig().
grunt.initConfig({
cachebuster: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
},
},
})Type: String
Default value: ''
If specified, this text is inserted at the top of the generated file. Take care that the banner will be valid in the
chosen file format - e.g. if options.format is 'json' then banner should be a javascript comment, and in that case
only if your json parser supports comments; if options.format is 'php', then the banner will be inserted after the
<?php line and the banner should be specified as a valid php code or comment(s).
You may use Grunt templates in the banner, for example:
banner: '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +
'<%= grunt.template.today("yyyy-mm-dd") %> */'Type: String
Default value: none
If specified, source filenames will be converted to be relative to this path when they are written to the destination file. For example, given the following configuration:
grunt.initConfig({
cachebuster: {
build: {
options: {
banner: '<%= meta.custom_banner %>',
format: 'json',
basedir: 'src/assets/'
},
src: [ 'src/assets/filename1', 'src/assets/folder1/filename2' ],
dest: 'target/cachebusters.json'
}
},
)the resulting target/cachebusters.json would be:
{"filename1":"fa6a5a3224d7da66d9e0bdec25f62cf0","folder1/filename2":"5ba48b6e5a7c4d4930fda256f411e55b"}Type: Function|String
Default value: md5
If specified it will generate a hash of the specific algorithms supported by crypto.createHash(). By passing a
function you can implement your own hash function. The passed function will receive the buffer of the file to be
hashed.
Type: Boolean
Default value: false
If set to true, hashes will be generated for each directory in the file list, rather than just the files. This can
be useful if you just want a single hash used for a whole set of resources and avoids the output file ballooning in
size.
Type: Number
Default value: no length, default length of the hash function
If specified, the hash will be truncated to the value of length.
Type: Function
Default value: none
If specified, this function will be called, passing the finished hashes object as its sole parameter, and its return value will be processed through the configured formatter for writing to the destination file. This can be used to augment the hashes in some way before the file is generated.
This may be useful if you're using the 'php' output format, but you need your php array structure to be different
to the default. For example, this function can be used to nest the array inside a parent array for use as a Laravel
configuration file:
grunt.initConfig({
laravel-cachebuster-configuration: {
options: {
basedir: 'public/',
format: 'php',
banner:
'/**\n' +
' * GENERATED FILE, DO NOT EDIT. This file is simply a collection of generated hashes for static assets in \n' +
' * the project. It is generated by grunt, see Gruntfile.js for details.\n' +
' */'
complete: function(hashes) {
return {
md5: hashes
};
}
},
src: ['public/**/*'],
dest: 'application/config/cachebuster.php'
},
})The resulting 'application/config/cachebuster.php' file will contain something like:
<?php
/**
* GENERATED FILE, DO NOT EDIT. This file is simply a collection of generated hashes for static assets in
* the project. It is generated by grunt, see Gruntfile.js for details.
*/
return array(
'md5' => array(
'js/main.js' => 'ae65552d65cd19ab4f1996c77915ed42',
'js/vendor/modernizr-2.6.2.min.js' => 'b8009fa783ea3de3802efcd29d7473d5',
'img/bg/about.jpg' => '7e402c1d64f0b00b4ade850f9017556a',
'crossdomain.xml' => '625e6c239ea0b5504ce0641b74ec2a3b',
)
);Type: String
Default value: 'json'
Supported values: 'json', 'php'
Specifies in which format the destination file will be generated.
Type: Function
Default value: none
If options.formatter is specified, then options.format will be ignored and the specified function will be called
instead to generate the contents of the destination file.
The function will be passed two arguments, hashes and banner, and is expected to return a string. The returned
string will be written unmodified to the destination file.
Function arguments:
hashes: an object containing the MD5 hashes of all specified source files keyed by filename.banner: the banner string to be prepended to the output, or an empty string if no banner was configured.
Example hashes parameter:
{
"path/to/filename1" : "fa6a5a3224d7da66d9e0bdec25f62cf0",
"path/to/filename2" : "5ba48b6e5a7c4d4930fda256f411e55b"
}In this example, the default options are used; so the files src/file1 and src/file2 will each be read, and their
MD5 hashes will be written into the file dest/cachebusters.json in the default format, which is JSON.
grunt.initConfig({
cachebuster: {
options: {},
files: {
'dest/cachebusters.json': ['src/file1', 'src/file2'],
},
},
})In this example, the use of a custom formatter allows writing the MD5 hashes of the source files to the destination file in CSV format.
grunt.initConfig({
cachebuster: {
options: {
basedir: 'src/assets/',
formatter: function(hashes) {
var output = '"Filename","Hash"\n';
for (var filename in hashes) {
output += '"' + filename + '","' + hashes[filename] + '"\n';
}
return output;
}
},
src: 'src/assets/**/*',
dest: 'dest/cachebusters.csv'
}
})In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
(Nothing yet)