grunt-hashly is a grunt binding for hashly, which is a build-time tool that enables cache-busting for static files (images, JavaScript, CSS, etc).

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-hashly --save-dev

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

grunt.loadNpmTasks('grunt-hashly');

Run this task with the grunt hashly command.

Task targets, files and options may be specified according to the grunt Configuring tasks guide.

This task offers all the same options as the hashly command line interface, so please refer to the documentation for advanced configuration.

Type: String (required)

Sets the base path to use (from which all paths will be root-relative) when generating the hashly manifest file.

Type: String Default: basePath

Optionally specify a target directory to which hashed files and the manifest should be copied. If not specified, files are hashed in-place.

Type: String Default: json

Optionally specify the format of the manifest file. Currently supports "json", "json-object" (json with original path as key) or "tab" (tab delimited). Default is "json".

Type: String Default: json

Specifies a path for the manifest file. If not specified, the manifest is named "manifest.{ext}" and is placed in the destination directory root.

Type: Boolean Default: false

If true, image paths in CSS files are rewritten to point to the hashed versions of the images. This ensures that when images change, the url of the CSS that references them also changes.

Type: String

Optionally specify a comma-delimited list of globbing patterns to use to include files to be hashed/copied.

Type: String

Optionally specify a comma-delimited list of globbing patterns to use to exclude files from being hashed/copied.

Type Boolean Default false

A globbing expression. Any matching files will be copied as-is to the destination folder. Has no effect if the destination is the same as the source.

Type Boolean Default False

Instructs hashly to amend an existing manifest, where it would normally delete and recreate it from scratch. This is useful for incrementally adding to a large filesystem.

Type Boolean Default False

Use the file size for binary files instead of the file contents. This makes processing large binary files extremely quick, though at a (extremely slight) risk that a hashcode will not change when a file is updated.

Type Integer Default 32

Specifies the length of the hash used when renaming files. Default is 32 characters.

Type: String

Specifies the format to use when renaming files. Variables are specified using curly brackets (e.g., {variable}). Any other characters are directly included in the output.

Available variables include:

• {basename}: the base filename without extension
• {hash}: the hash value
• {extname}: the file extension

Default is "{basename}-hc{hash}{extname}".

Type Boolean Default False

Ignore errors. Otherwise, hashly will abort on the first error.

Type Boolean Default False

Ignore errors from plugins. Takes precedence over continueOnError.

Type: String

Semicolon-delimited list of plugin names that should be disabled.

Type Integer Default 0

Deletes files that aren't in the manifest and are older than the specified number

Type: Boolean Default: True

Include the absolute path to the source map in the JS/CSS source, relative to base-dir.

Type: String

A URL prefix to apply to the source map tag, if it is not in the same location as the source.

This configuration will output all hashed files and the manifest in place.

grunt.initConfig({
  hashly: {
    my_target: {
      basePath: "./staticFiles"
    }
  }
});

This configuration will output all hashed files and the manifest in the specified target directory.

grunt.initConfig({
  hashly: {
    my_target: {
      basePath: "./staticFiles",
      targetPath: "./staticFilesProcessed"
    }
  }
});

This configuration will output all hashed files and the manifest in place, with the manifest in tab-delimited format.

grunt.initConfig({
  hashly: {
    my_target: {
      basePath: "./staticFiles",
      options: {
        manifestFormat: "tab"
      }
    }
  }
});

This configuration will exclude any *.pdf files from being hashed.

grunt.initConfig({
  hashly: {
    my_target: {
      basePath: "./staticFiles",
      options: {
        exclude: "*.pdf"
      }
    }
  }
});