Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Cache bust static assets using content hashing

branch: master


Build Status

Bust static assets from the cache using content hashing

Getting Started

If you haven't used grunt before, be sure to check out the Getting Started guide.

From the same directory as your project's Gruntfile and package.json, install this plugin with the following command:

npm install grunt-cache-bust --save-dev

Once that's done, add this line to your project's Gruntfile:


If the plugin has been installed correctly, running grunt --help at the command line should list the newly-installed plugin's task or tasks. In addition, the plugin should be listed in package.json as a devDependency, which ensures that it will be installed whenever the npm install command is run.

The "cacheBust" task

Use the cacheBust task for cache busting static files in your application. This allows them to be cached forever by the browser, just point the task towards any file that contains references to static assets.

Currently supported static assets: CSS, JavaScript, images and favicons

Note: Remote URLs for CSS, JavaScript, and images are ignored by cacheBust. This assumes that remote URLs for these assets will be CDN hosted content, typically for well known libraries like jQuery or Bootstrap. For example, all of below URLs will be ignored:

<link href="//" rel="stylesheet">
<link href="" rel="stylesheet">
<script src="//"></script>
<script src=""></script>
<script type="text/javascript" src=""></script>
<img src="" alt="test" />


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

  cacheBust: {
    options: {
      encoding: 'utf8',
      algorithm: 'md5',
      length: 16
    assets: {
        files: [{
            src: ['index.html']



Type: String Default value: 'utf8'

The encoding of the file contents.


Type: String Default value: 'md5'

algorithm is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are 'sha1', 'md5', 'sha256', 'sha512'


Type: Number Default value: 16

The number of characters of the file content hash to prefix the file name with.


Type: Boolean Default value: false

When true, cachebust will rename the reference to the file and the file itself with the generated hash. When set to false, then a query string parameter is added to the end of the file reference.


Type: String Default value: false

When set, cachebust will try to find the asset files using the dir as base path.


Type: Boolean Default value: false

When true, cachebust will search single- and double-quoted strings in scripting languages such as PHP for asset paths. Asset paths must have the "#grunt-cache-bust" URL fragment appended. See Usage Examples section below.


Type : Object Default value:

    'script' : function() { return this.attr('src'); },
    'link[rel="stylesheet"]' : function() { return this.attr('href'); },
    'img' : function() { return this.attr('src'); },
    'link[rel="icon"], link[rel="shortcut icon"]' : function() { return this.attr('href'); }

When set, filters will be merged with the default (above). These filters are 'selector' : Function mapper | Function mapper[]. Where the mapper function or array of functions returns the String file paths.

Usage Examples

Basic Asset Cache Busting

  cacheBust: {
    files: {
      src: ['index.html', 'contact.html']

Custom Options

  cacheBust: {
    options: {
      algorithm: 'sha1',
      length: 32,
      baseDir: '.tmp/public/',
      filters: {
        'script' : [
            function() { return this.attr('data-main');} // for requirejs mains.js
            function() { return this.attr('src'); }, // keep default 'src' mapper
    files: [{
      expand: true,
      cwd: 'src',
      src: ['*.html'],
      dest: 'dest/'

URL-Fragment Hints

  cacheBust: {
    options: {
      enableUrlFragmentHint: true
    files: ['example.php']

Before cache bust:

// example.php
$foo = '/some/asset/path.jpg#grunt-cache-bust';
$other = '/wont/be/busted.jpg';

After cache bust:

// example.php
$foo = '/some/asset/path.jpg?fa59cbed61b15262#grunt-cache-bust';
$other = '/wont/be/busted.jpg';
Something went wrong with that request. Please try again.