grunt-cache-breaker

<!-- Turn this -->
<script src="/js/dist/combined.min.js"></script>
 
<!-- into this -->
<script src="/js/dist/combined.min.js?rel=123456"></script>
 
<!-- or this -->
<script src="/js/dist/combined.min.123456.js"></script>
 
<!-- or this (md5 hash of file contents) -->
<script src="/js/dist/combined.min.ow23de343.js"></script>

Getting Started

This plugin requires Grunt ~0.4.1

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

grunt.loadNpmTasks('grunt-cache-breaker');

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 key 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 app.js?rel=v_2_0

// Append a custom string to 'all.js' which is located in 'index.html'
cachebreaker: {
    dev: {
        options: {
            match: ['all.js'],
            replacement: function (){
                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 string
cachebreaker: {
    dev: {
        options: {
            match: ['all.js'],
            position: 'filename',
            replacement: function (){
                return "v_2_0"
            }
        },
        files: {
            src: ['index.html']
        }
    }
}

Options

Option	Type	Default	Description
match	string	array	null
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

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.