Grunt.js Plugin that renames asset files with a content hash and stores hashes in a JSON file. (based off of grunt-wp-assets by Hariadi Hinta)
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Rename assets files with hash and store in a JSON file

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-version-json --save-dev

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



This plugin is a modified version of grunt-wp-assets by Hariadi Hinta (Thank you, Hariadi Hinta!). Much is carried over from his plugin, but instead of modifying a WordPress-specific functions.php file with file hashes, the file hashes are saved to a JSON file like so: { "path/to/file.ext": "SOMEHASH", "path/to/other-file.ext": "SOMEHASH" }.

The idea is to remove the burden of storing file hashes from a WordPress-specific file and into a more universal and single-purpose JSON file so this plugin should be usable outside the context of WordPress projects. To access the JSON file from WordPress/PHP, I use something like:

$json = file_get_contents(get_template_directory() . '/filerevs.json');
$filerevs = json_decode($json, true);
wp_register_script('mysite-scripts', get_template_directory_uri() . '/assets/js/scripts.min.' . $filerevs['assets/js/scripts.min.js'] . '.js', false, null, true);
wp_register_style('mysite-style', get_template_directory_uri() . '/assets/css/style.min.' . $filerevs['assets/css/style.min.css'] . '.css', false, null);

(the above example assumes that the file hashes are stored to a JSON file named filerevs.json. The JSON file is defined in the dest property of the asset_version_json task config)

Usage Example

asset_version_json: {
  assets: {
    options: {
      algorithm: 'sha1',
      length: 8,
      format: false,
      rename: true
    src: 'assets/css/main.min.css',
    dest: 'filerevs.json'

This example task will rename assets/css/main.min.css to assets/css/main.min.{sha1hash}.css and update assets reference in filerevs.json which would look something like { "assets/css/main.min.css": "SOMEHASH" };


If the JSON file defined by the dest property does not exist, then it will fail. Also if the file exists but does not already contain a JSON object (at least {}), then it will fail.



Type: Boolean Default: false

It will rename the src target instead of copy.


Type: Boolean Default: true

File name format.

true: {hash}.{filename}.{ext}
false: {filename}.{hash}.{ext}


Type: String Default: 'utf8'

The file encoding.


Type: String Default: 'md5'

algorithm is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', etc. On recent releases, openssl list-message-digest-algorithms will display the available digest algorithms.


Type: Number Default: 4

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

Release History

  • 2013-11-21   v0.1.4   Update readme php/wordpress example
  • 2013-11-21   v0.1.3   track full file pathnames as supplied to the 'src' property rather than using the base filename
  • 2013-11-21   v0.1.2   Track hashes by individual file rather than by filetype
  • 2013-11-21   v0.1.1   Update readme
  • 2013-11-21   v0.1.0   Initial commit.