grunt-bust

Insert MD5 hash of file into urls referencing that file

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-bust --save-dev

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

grunt.loadNpmTasks('grunt-bust');

The "bust" task

Overview

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

grunt.initConfig({
  bust: {
    options: {
        bustable: [ '**/*.html' ],
        regexes: [{
            filepath: 'js/index.js',
            regex: /(require\(\['index)/g
        }],
        basePath: 'test/fixtures/',
        prepend: 'bust',
    },
    your_target: {
          files: [{
              expand: true,     // Enable dynamic expansion.
              src: ['test/fixtures/require.html'], // Actual pattern(s) to match.
              dest: 'tmp/'   // Destination path prefix.
          }]
    },
  },
})

Options

options.bustable

Type: Array

An Array of string file path globs matching the files that might have a url referencing it.

options.regexes

Type: Array Default value: []

An array of objects mapping a pattern to a filepath

options.prepend

Type: String Default value: 'cbuster-'

A string to insert before the md5 inserted into urls. This is handy for url rewrites; it gives the rewrite something predictable to search for.

options.basePath

Type: String Default value: ''

Treat any files at basepath as if they are at the webroot. Eg. a basepath of public for a file public/js/jquery.js will cause the url js/jquery.js to match the file public/js/jquery.js

options.baseDir

Type: String Default value: ''

filepaths will be converted to be relative to baseDir

Usage Examples

Default Options

In this example, the default options replace all references to all files in html files.

grunt.initConfig({
  bust: {
    options: {
    },
    files: [{
        expand: true,     // Enable dynamic expansion.
        src: [
            '**/*.html'
        ],
        dest: '../dist/'   // Destination path prefix.
    }]
  }
})

Custom Options

In this example, regexes are used to insert a cachebuster after a require.js include. All cachebusters are prepended with bust instead of cbuster-, and only js files are replaced.

grunt.initConfig({
  bust: {
    options: {
        regexes: [{
            filepath: 'js/index.js',
            regex: /(require\(\['index)/g //'])
        }],
        basePath: 'app/',
        prepend: 'bust',
        bustable: [ 'js/**/*.js' ]
    },
    files: [{
        expand: true,     // Enable dynamic expansion.
        src: [
            '**/*.html',
            '!node_modules/**/*.html'
        ],
        dest: '../dist/'   // Destination path prefix.
    }]
  }
})

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)