Simple cache-breaker, appends a timestamp or md5 hash to any urls
<!-- Turn this --><!-- into this --><!-- or this --><!-- or this (md5 hash of file contents) -->
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-cache-breaker --save-dev
Once the plugin has been installed, add this to your Gruntfile.js
And then add one of the following to your list of tasks
##Usage ###(all examples require version 1.0.0 or above)
Append timestamps as query strings
Very useful in the development stages, not to be used in production though (see the other examples)
// Append a timestamp to 'all.min.js' & 'core.min.js' which are both located in 'index.html'cachebreaker:dev:options:match: 'all.min.js' 'core.min.css'files:src: 'index.html'
Append timestamps as filename changes
A great idea if you have server rewrites. The file names are not changed, just changed in the markup.
File urls will be rewritten to
all.min.4252425.js, for example
// Append a timestamp to 'all.min.js' & 'core.min.js' which are both located in 'index.html'cachebreaker:dev:options:match: 'all.min.js' 'core.min.css'position: 'filename'files:src: 'index.html'
Append timestamps as filename changes in certain positions
Again, to be used with server rewrites, this allows you specify which 'piece' of the filename is rewritten.
File urls will be rewritten to
all.4252425.js, for example.
// Append a timestamp to 'all.min.js' & 'core.min.js' which are both located in 'index.html'cachebreaker:dev:options:match: 'all.*.js' 'core.*.css'position: 'overwrite'files:src: 'index.html'
##MD5 hash Use the contents of a file to generate a hash instead of a timestamp. Works in all positions mentioned above.
This example will create links like this:
all.min.js?rel=hetweyj332 - which is useful as your templates only change
when the contents of the file change.
// Append a md5 hash to 'all.js' which is located in 'index.html'cachebreaker:dev:options:match: 'all.js'replacement: 'md5'src:path: 'app/all.js'files:src: 'index.html'
##Multiple MD5 hashs (v2.0.0 required)
Use the contents of multiple files to generate a hash for each.
NOTE: When passing an object to the
match array like this, each
is the pattern to search for in the html file & the value is the actual
file to be hashed.
If you're not sure, check the Gruntfile.js in this project for working examples.
// Append a md5 hash to 'all.js' & `script.js` which is located in 'index.html'cachebreaker:dev:options:match:// Pattern // File to hash'script.js': 'test/fixtures/js/script.js''app.js': 'test/fixtures/js/app.js'replacement: 'md5'files:src: 'index.html'
##Custom replacement You can also provide your own replacement if the Timestamps or MD5 hashes are not right for you.
This example would change the URL of app.js, to
// Append a custom string to 'all.js' which is located in 'index.html'cachebreaker:dev:options:match: 'all.js'return "v_2_0"files:src: 'index.html'
Of course, as with all examples, you're free to mix & match the options. For example, you could use the custom method above, but to change the filename in the markup instead of a query string.
// Change filename in the markup to include custom stringcachebreaker:dev:options:match: 'all.js'position: 'filename'return "v_2_0"files:src: 'index.html'
|replacement||string||function||"time"||"time", "md5", or custom function|
|position||"string"||"append"||"append", "filename", "overwrite"|
|src.path||"string"||null||Path to file to be used for md5 hash|
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.