grunt-asset-cachebuster

    0.5.0 • Public • Published

    grunt-asset-cachebuster

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

    Getting Started

    This plugin requires Grunt >=0.4.0

    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(),
          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 extension of a 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.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');
    }

    or

    <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');
    }

    or

    <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');
    }

    or

    <script src="testing.js"></src>
    <script src="//my.cdn.example.com/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=0.1.0');
    }
    h2 {
      background-image: url('//my.cdn.example.com/testing.png');
    }

    or

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

    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

    • 2016-02-28 v0.5.0 update peer dependencies to add support for grunt 1.0.0 release
    • 2015-12-08 v0.4.0 add support for cachebusting SVG files. Contributed by @kyusu
    • 2014-05-01 v0.3.1 fix: images in HTML other than png were not busted
    • 2014-01-08 v0.3.0 allow a function as a buster. Contributed by @tleruitte
    • 2013-12-01 v0.2.0 add support for ignoring urls based on strings
    • 2013-11-07 v0.1.1 fix documentation
    • 2013-10-07 v0.1.0 initial release

    Install

    npm i grunt-asset-cachebuster

    DownloadsWeekly Downloads

    336

    Version

    0.5.0

    License

    none

    Last publish

    Collaborators

    • gillesruppert