grunt-urlCacheBuster

Apply version strings to URLs within your CSS/HTML files to load uncached media.

Getting Started

This plugin requires Grunt ~0.4.5

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

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

grunt.loadNpmTasks('grunt-urlCacheBuster');

The "urlCacheBuster" task

Overview

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

grunt.initConfig({
  urlCacheBuster: {
    files: {
      'dest/example.css': 'src/example.css',
    }
  }
});

Options

options.version

Type: String Default value: Date().getTime()

This is the value that is appended to the end of your URLs. If nothing is set the default is set to a timestamp returned by Date().getTime().

options.version_key

Type: String Default value: cacheBuster

Used as the key for the cacheBuster param, the default "cacheBuster" would look like this for example: http://example.com/someimage.jpg?cacheBuster=abc123

options.formats

Type: Array Default value: ['jpg', 'jpeg', 'png', 'gif']

Specify which media types you want to add version strings to.

Usage Examples

Default Options

grunt.initConfig({
  urlCacheBuster: {
    files: {
      'dest/example.css': 'src/example.css',
    }
  }
});

Custom Options

Couple of examples showing custom options with different file patterns and formats.

grunt.initConfig({
  urlCacheBuster: {
    custom_one: {
        options: {
            version_key: "v",
            version: "0.1.0",
            formats: ['jpg']
        },
        files: [{
            expand: true,
            cwd: 'src/',
            src: 'example/*.css',
            dest: 'dest/',
            ext: '.css'
        }]
    },
    custom_two: {
        options: {
            version_key: "v",
            version: "0.1.0",
            formats: ['jpg', 'ttf', 'woff', 'woff2']
        },
        files: [{
            expand: true,
            cwd: 'src/',
            src: 'example/*',
            dest: 'dest/'
        }]
    },
  }
});

File Formats

The plugin was developed with CSS files in mind but it can be used with any text file that grunt.file.read(filepath [,options]) can read. The plugin looks for and manipulates url strings based on the formats supplied, bare in mind that every matching string will be cache busted.

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)