grunt-cache-busting

Cache busting files and updating references

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:

npm install grunt-cache-busting --save-dev

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

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

Usage

'cache-busting': {
    requirejs: {
        replace: ['tmp/**/*.html'],
        replacement: 'MainApp',
        file: 'tmp/deploy/js/app/MainApp.min.js'
    },
    css: {
        replace: ['tmp/**/*.html'],
        replacement: 'style.css',
        file: 'tmp/deploy/css/style.css',
        cleanup: true //Remove previously generated hashed files.
    }
},

Say that the index.html looks like this:

<html>
<head>
    <link rel="stylesheet" href="https://github.com/PaulTondeur/grunt-cache-busting/blob/master/css/style.css" />

    <script data-main="js/app/MainApp" src="https://github.com/PaulTondeur/grunt-cache-busting/raw/master/js/vendors/requirejs/require.js"></script>
</head>
<body>

</body>
</html>

After running grunt cache-busting, this file will look like this, and the files have changed accordingly on disk:

<html>
<head>
    <link rel="stylesheet" href="https://github.com/PaulTondeur/grunt-cache-busting/blob/master/css/style-HASH-OF-FILE-CONTENTS.css" />

    <script data-main="js/app/MainApp-HASH-OF-FILE-CONTENTS" src="https://github.com/PaulTondeur/grunt-cache-busting/raw/master/js/vendors/requirejs/require.js"></script>
</head>
<body>

</body>
</html>

Optionally, you can pass the get_param option to simply append a query string parameter to the path of the file. This is useful if you need to change the contents of a file, but not the filename.

Note: Some proxy servers do not re-request assets when a new query string is used. If a significant portion of your users use proxy servers, you may want to change the filename instead of appending a query string.

'cache-busting': {
    css: {
        replace: ['tmp/**/*.html'],
        replacement: 'style.css',
        file: 'tmp/deploy/css/style.css',
        get_param: true,
    }
},

Will change the html above to this:

<html>
<head>
    <link rel="stylesheet" href="https://github.com/PaulTondeur/grunt-cache-busting/blob/master/css/style.css?v=HASH-OF-FILE-CONTENTS" />

    <script data-main="js/app/MainApp-HASH-OF-FILE-CONTENTS" src="https://github.com/PaulTondeur/grunt-cache-busting/raw/master/js/vendors/requirejs/require.js"></script>
</head>
<body>

</body>
</html>

API reference

replace

replace is an array of source files that is searched for the strings to be replaced. It supports minimatch paths.

replacement

replacement is a string for which we search and replace by the hash. If it contains an extension, the extension will be preserved.

file

file is the file which will be renamed to filename-HASH-OF-FILE-CONTENTS.ext. The hash is generated based on the file contents of this parameter.

Credits

This plugin is build on top of grunt-text-replace and was inspired by grunt-cache-bust

PaulTondeur / grunt-cache-busting

readme