Generates a file containing file hashes
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
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-dev
In your project's Gruntfile, add a section named
cachebuster to the data object passed into
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
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") %> */'
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:
target/cachebusters.json would be:
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
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
Default value: no length, default length of the hash function
If specified, the hash will be truncated to the value of
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
'application/config/cachebuster.php' file will contain something like:
Specifies in which format the destination file will be generated.
Default value: none
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,
banner, and is expected to return a string. The returned
string will be written unmodified to the destination file.
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.
"path/to/filename1" : "fa6a5a3224d7da66d9e0bdec25f62cf0""path/to/filename2" : "5ba48b6e5a7c4d4930fda256f411e55b"
In this example, the default options are used; so the files
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.
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.
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.