grunt-cachebuster

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.

Getting Started

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:

``shell
npm install grunt-cachebuster --save-dev
`

One the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

`js
grunt.loadNpmTasks('grunt-cachebuster');
`

The "cachebuster" task

$3


In your project's Gruntfile, add a section named cachebuster to the data object passed into grunt.initConfig().

`js
grunt.initConfig({
cachebuster: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
},
},
})
`

$3

#### options.banner
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
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:

`js
banner: '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +
'<%= grunt.template.today("yyyy-mm-dd") %> */'
`

#### options.basedir
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:

`js
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:

`js
{"filename1":"fa6a5a3224d7da66d9e0bdec25f62cf0","folder1/filename2":"5ba48b6e5a7c4d4930fda256f411e55b"}
`

#### options.hash
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.

#### options.includeDirs
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.

#### options.length
Type: Number
Default value: no length, default length of the hash function

If specified, the hash will be truncated to the value of length.

#### options.complete
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:

`js
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',
)
);
`

#### options.format
Type: String
Default value: 'json'
Supported values: 'json', 'php'

Specifies in which format the destination file will be generated.

#### options.formatter
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:

`js
{
"path/to/filename1" : "fa6a5a3224d7da66d9e0bdec25f62cf0",
"path/to/filename2" : "5ba48b6e5a7c4d4930fda256f411e55b"
}
`




$3

#### Default Options
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.

`js
grunt.initConfig({
cachebuster: {
options: {},
files: {
'dest/cachebusters.json': ['src/file1', 'src/file2'],
},
},
})
`


#### Custom Options
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.

`js
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'
}
})
``

Contributing

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.

Release History

_(Nothing yet)_