Have opinions about JavaScript? We want to hear them. Take the 2018 JavaScript Ecosystem Survey »


0.1.6 • Public • Published


Powerful hash | cache busting plugin for grunt

Table of content


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-hash-extended --save-dev

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


or by using the load-grunt-tasks


Run this task with the grunt hash-extended command.


There are a number of options available:

    files: <file>
            cwd: <cwd>
            src: ['<globbing>','<pattern>']
            baseRefDir: '<base directory the references will be calculated from>'
            requirejs: true|false
        hashAlgorithm    : 'md5',
        hashLength       : 8,
        hashPrefix       : 'zhn'
        renameFile       : true,
        removeSource     : false,
        onComplete       : null,
        encoding         : 'utf8',
        fileMap          : null


Type: Files Array Format

Those are the files you want to HASH


Type: Custom Files Array Format

Those files are the files you want to have references updated. Those should not contain any binary files.

            cwd: <cwd>
            src: ['<globbing>','<pattern>']
            baseRefDir: '<base directory the references will be calculated from>'
  • cwd
    as for normal File Array Format

  • src
    as for normal File Array Format

  • baseRefDir
    the reference base path.
    This is useful for instance when you have backend files hosted outside your served folder, like myproject/views/*.twig and the served folder being for instance myproject/web. The references in the .twig files should be based on the myproject/web path. In this case, baseRefDir would be myproject/web

  • requirejs optional, default to false If this is true, the regular expression to look for reference will omit the extensions. so for instance the regex /('|")(my/path/my/script.min.js)(.*?)['|"]/g will become /('|")(my/path/my/script.min)(.*?)['|"]/g


Type: String
Default: 'md5'

This defines what algorithms to be used to generate the hash. It is dependent on the available algorithms supported by the version of OpenSSL on the platform.
Examples are 'sha1', 'md5', 'sha256', 'sha512', etc.
see NodeJS Crypto library for more information


Type: Integer
Default: 8

This defines the length of the hash.


Type: String
Default: 'zhn'

This defines a hash prefix that will be appended to the hash itself. This is to make it simpler for some specific use cases (see examples bellow)


Type: Boolean
Default: true

This defines if the hash files should be renamed or not, using the following logic <filename>-<hashPrefix><hash>.<ext>


Type: Boolean
Default: false

This defines if the hashed files (just renamed/copied) sources' should be removed.


Type: Function
Default: null

This defines a callback function to be called when the task is completed. This helps you to handle the hash map, so you can write the output to json or sth.
function(map, files) where:

  • map is an object where the keys are the file sources and the values are the file destinations
  • files is an array of the file sources


Type: String
Default: 'utf8'

This defines the encoding used when writing / copying the files


Type: String
Default: 'utf8'

This defines the encoding used when writing / copying the files


Type: String
Default: null

This defines a file where the map json object will be saved.
By default (null) the map won't be saved.


In the following example we will NOT rename the files but just the references of those files. It means that our application will try to download files named <filename>-zhn<hash>.<ext>. To cater for this you will have to add a rule on your server to rewrite it to the file, for instance in Apache with mod_rewrite enabled:

RewriteRule (^.*)(-zhn.+?)\.(.+)$ $1.$3 [L]

The grunt task will look like this

/* global module,require */
module.exports = function (grunt) {
    'use strict';
    // Load grunt tasks automatically
        // Project settings
        application: {
            'src'    : 'app',
            'dist'   : '../../dist/apps/login'
        'hash-extended' : {
            all : {
                files : [
                        expand : true,
                        cwd    : '<%= application.dist %>/web',
                        src    : [
                        dest   : '<%= application.dist %>/web'
                references: [
                        cwd    : '<%= application.dist %>/web',
                        src    : [
                        cwd         : '<%= application.dist %>/views',
                        src         : [ '**/*.twig' ],
                        baseRefDir  : '<%= application.dist %>/web'
                options : {
                    //  the hash algorithm
                    hashAlgorithm   : 'md5',
                    //  the hash length
                    hashLength      : 8,
                    //  the hash prefix
                    hashPrefix      : 'zhn'
                    //  do we want to rename the files
                    renameFile: false,
                    // should we removed the source files?
                    removeSource : false,
                    // function to handle the hash map
                    // so you can write the output to json or sth ;-)
                    // in this case, we write json AND php output of our map :-)
                    onComplete  : function ( map, files ) {
                        var arr = [];
                        files.forEach( function ( file ) {
                            arr.push( '\'' + file + '\'=>\'' + map[ file ] + '\'' );
                        var out = '<?php\n\n$files = [\n\t' + arr.join( ',\n\t' ) + '\n];\n';
                        //grunt.file.write( 'test/dist/map.php', out );
                        grunt.file.write( application.dist + '/map.json', JSON.stringify( map ) );

Release History

  • 2015-10-12   v0.1.6   Path and regex OS independent
  • 2015-09-29   v0.1.5   Removed unnecessary logs
  • 2015-09-29   v0.1.4   Improved regex
  • 2015-09-29   v0.1.3   Fixed error when no references passed
  • 2015-09-29   v0.1.2   Fixed own reference throwing error.
  • 2015-09-29   v0.1.1   Updated regex
  • 2015-09-13   v0.1.0   Updated regex, fixed no map when referencing only.
  • 2015-03-13   v0.0.10   Fixed looping issue.
  • 2015-03-13   v0.0.9
    • adding RequireJS support and updated documentation and options
    • updated the documentation to have the rewrite rule working with minified extensions
  • 2015-03-12   v0.0.8   Fixed path generation on windows OS ('\' replaced with '/')
  • 2015-03-12   v0.0.7   Fixed regex generation on windows OS ('\' replaced with '/')
  • 2015-03-12   v0.0.6   Forgot to bump the version number in documentation
  • 2015-03-12   v0.0.5   Fixed unwanted dependency
  • 2015-03-12   v0.0.4   Fixed options variable name not following documentation
  • 2015-03-11   v0.0.3   Updating documentation
  • 2015-03-11   v0.0.2   Updating documentation
  • 2015-03-11   v0.0.1   Initial release


npm i grunt-hash-extended

Downloadsweekly downloads








last publish


  • avatar
Report a vulnerability