grunt-bust

Insert MD5 hash of file into urls referencing that file

npm install grunt-bust
25 downloads in the last month

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)

npm loves you