node package manager


grunt-hashres has been updated to Grunt 0.4. if you're still using Grunt 0.3.x go to old version documentation


Hashes your js and css files and rename the <script> and <link> declarations that refer to them in your html/php/etc files.

Getting Started

Install this grunt plugin next to your project's Gruntfile.js with: npm install grunt-hashres

Then add this line to your project's grunt.js gruntfile:



Add the following to your Gruntfile.js file, inside the initConfig function:

hashres: {
  // Global options 
  options: {
    // Optional. Encoding used to read/write files. Default value 'utf8' 
    encoding: 'utf8',
    // Optional. Format used to name the files specified in 'files' property. 
    // Default value: '${hash}.${name}.cache.${ext}' 
    fileNameFormat: '${hash}.${name}.cache.${ext}',
    // Optional. Should files be renamed or only alter the references to the files 
    // Use it with '${name}.${ext}?${hash} to get perfect caching without renaming your files 
    // Default value: true 
    renameFiles: true,
    // Optional. For user to customize what to find, useful when you have cssmin or uglify task before hashres 
    // For example, I use 'src/core/admin.css' in template file, and have minified version in 'dist/core/admin.min.css', and a hash-reved version in 'dist/core/admin.min.xxxxxxxx.css' 
    // I want to replace all occurence of 'src/core/admin.css' with 'dist/core/admin.min.xxxxxxxx.css', but the default behavior just replace 'dist/core/admin.min.css' 
    // params: 
    //  - souce: dist/core/admin.min.css 
    //  - renamed: dist/core/admin.min.xxxxxxxx.css 
    //  - src: dist/core/admin.min.xxxxxxxx.css 
    patternMaker: function (source, renamed, src) {
      return source;
    // Optional. For user to customize replacement, used as companion with patternMaker 
    replacementMaker: function (source, renamed, src) {
      return renamed;
  // hashres is a multitask. Here 'prod' is the name of the subtask. You can have as many as you want. 
  prod: {
    // Specific options, override the global ones 
    options: {
      // You can override encoding, fileNameFormat or renameFiles 
    // Files to hash 
    src: [
      // WARNING: These files will be renamed! 
    // File that refers to above files and needs to be updated with the hashed name 
    dest: 'dist/prod/home.php',

The way this task works follows my workflow: I only hash the .js and .css files of my production release files, which are first both uglified and minified. If you want to hash a different set of files for a different environment, simply add another subtask under hashres.

Heads up:

If you have upgraded from Grunt 0.3 version: 'files' and 'out' config properties have been replaced by 'src' and 'dest'


  • src: A single file expression or an array of file expressions. Something like myscripts/*.js would be valid.
  • dest: The file expression(s) that refer to the hashed files and that will be updated with the new names. You can update more than one file specifying an array of output files: [out/fileOne.html, out/fileTwo.html]
  • encoding: Encoding used to read and write files. Using utf8 by default.
  • fileNameFormat: The files specified in property files will be renamed according to the pattern specified in this property. The following variables are allowed:
    • ${hash}: the first 8 digits of the md5 of the file.
    • ${name}: the original name of the file.
    • ${ext}: the original extension of the file.
  • renameFiles: Rename the files or leave them in place and only alter the references to them in out. Defaults to true


Build Status


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

  • 14/05/13 - 0.3.2: Bugfix #8: Replace all ocurrences. Thanks to kleinsch.
  • 20/02/13 - 0.3.0: Update to Grunt 0.4. Check out the documentation because some configuration properties have changed.
  • 19/11/12 - 0.2.1: Optional File Renaming. Thanks to raphaeleidus.
  • 14/11/12 - 0.1.5: Feature request #1: fileNameFormat property added.
  • 02/11/12 - 0.1.3: First working release.


Copyright (c) 2012 Luismahou Licensed under the MIT license.