grunt-asset-cachebuster

Cachebust images, scripts and other assets in your HTML & CSS files.

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-asset-cachebuster --save-dev

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

grunt.loadNpmTasks('grunt-asset-cachebuster');

The `asset_cachebuster` task

Overview

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

grunt.initConfig({
  asset_cachebuster: {
    options: {
      buster: Date.now(),
      replacer: '{url}?v={buster}',
      ignore: [],
      htmlExtension: 'html'
    },
    your_target: {
      // Target-specific file lists and/or options go here.
      // make sure you have separate file lists for your CSS and HTML files
    }
  }
})

Options

options.buster

Type: String | Function Default value: '123456'

A string value that is used to append to the url of your assets.

If it is a function, the function is called with the url and the destination file to cachebust as parameters, and it must return a string.

Generally, you want this to be a timestamp or the version number of your app.

options.replacer

Type: String Default value: {url}?v={buster}

A format string with two parameters: the URL being cachebusted and the buster token determined by options.buster.

options.htmlExtension

Type: String Default value: 'html'

The extension of html assets. This is useful if you use a templating language for your html where you want to cachebust assets, i.e. 'handlebars'

options.ignore

Type: Array Default value: []

Array of strings that if found in the url are not busted. This is useful if you have some assets on CDNs or in a particular folder that are never changed and hence should not be cachebusted.

Usage Examples

Default Options

grunt.initConfig({
  asset_cachebuster: {
    options: {},
    build: {
      files: {
        'dest/default_options.css': ['src/testing.css'],
        'dest/default_options.html': ['src/testing.html']
      }
    }
  }
})

In this example, the default options are used to cachebust html and css files. So if the testing.css or testing.html files have content such as

h1 {
  background-image: url('testing.png');
}

<script src="testing.js"></src>
<link href="testing.css" rel="stylesheet">
<img src="testing.png">

the generated result would be

h1 {
  background-image: url('testing.png?v=123456');
}

<script src="testing.js?v=123456"></src>
<link href="testing.css?v=123456" rel="stylesheet">
<img src="testing.png?v=123456">

Custom Options

grunt.initConfig({
  asset_cachebuster: {
    options: {
      buster: '0.1.0',
      ignore: [
        '//my.cdn.example.com'
      ],
      htmlExtension: 'htm'
    },
    build: {
      files: {
        'dest/default_options.css': ['src/testing.css'],
        'dest/default_options.htm': ['src/testing.htm']
      }
    }
  }
})

In this example, custom options are used to cachebust htm and css files. URLs that contain //my.cdn.example.com are not cachebusted. So if the testing.css or testing.htm files have content such as

h1 {
  background-image: url('testing.png');
}
h2 {
  background-image: url('//my.cdn.example.com/testing.png');
}

<script src="testing.js"></src>
<script src="//my.cdn.example.com/testing.js"></src>
<link href="testing.css" rel="stylesheet">
<img src="testing.png">