grunt-kapocs
Cache busting grunt plugin. Works with any file type.
Appends an MD5 hash to asset file names, and injects file names into templates.
Appending a hash to file names based on their contents ensures that each time a file's content changes, browsers will download the updated file from the server, rather than using the old, cached version. This is called cache busting.
A more detailed explanation of HTTP caching & cache busting.
Example project
Folder layout
Let's take the following folder layout:
project_folder
|- build
| |- <This is where we want the final output>
|- src
| |- assets
| | |- <Files that should be renamed, like images or videos>
| |- asset_templates
| | |- <Files that should be renamed, but also refer to other assets, like CSS or JS>
| |- templates
| |- <Files that refer to assets, but should NOT be renamed, like HTML>
|- Gruntfile.js
Config
Add the kapocs
task to the config object in Gruntfile.js like this:
kapocs: {
my_target: {
assets: [{
expand: true,
cwd: 'src/assets',
dot: true,
src: ['**'],
dest: 'build'
}],
assetTemplates: [{
expand: true,
cwd: 'src/asset_templates',
dot: true,
src: ['**'],
dest: 'build'
}],
templates: [{
expand: true,
cwd: 'src/templates',
dot: true,
src: ['**'],
dest: 'build'
}]
}
}
Run
Running grunt kapocs:my_target
will:
- Copy all the assets from
src/assets
tobuild
, appending a hash to their file names.
- A file called
src/assets/images/image.jpg
will be copied tobuild/images/image.<md5-hash>.jpg
.
- Copy all the files from
src/asset_templates
tobuild
, appending an MD5 hash to their file names, and expanding asset references in their contents.
- A file called
src/asset_templates/style/my-style.css
will be copied tobuild/style/my-style.<md5-hash>.css
. - If an asset template contains
{{image.jpg}}
or{{src/assets/images/image.jpg}}
, each such reference will be replaced withimage.<md5-hash>.jpg
.
- Copy all the files from
src/templates
tobuild
, expanding asset references in their contents.
- A file called
src/templates/index.html
will be copied tobuild/index.html
. - If a template contains
{{my-style.css}}
or{{src/asset_templates/style/my-style.css}}
, each such reference will be replaced withmy-style.<md5-hash>.css
.
Installing
You can install grunt-kapocs from NPM by doing:
npm install grunt-kapocs --save-dev
Don't forget to reference it in your Gruntfile.js
:
grunt.loadNpmTasks('grunt-kapocs');
Using
Add the kapocs
task to your Grunt config:
grunt.initConfig({
kapocs: {
my_target: {
options: {
// Options go here
},
assets: [
// JPG, PNG, MP4, and other assets
],
assetTemplates: [
// CSS, JS and other asset templates
],
templates: [
// HTML, PHP and other templates
]
}
}
});
The assets
, assetTemplates
and templates
arrays should contain Grunt file references in the format specified in the Grunt docs.
Each of these file references may also contain grunt.file.copy options. This allows you to specify an encoding
, for example.
Assets
Assets are usually binary files, like image or video files. You will want to append an MD5 hash to their file names to ensure they get cached only until they change.
Assets will be copied from the sources specified in src
to the destination folder specified in dest
.
They will also be renamed to include an MD5 hash in the file name, based on their contents.
A file called video.mp4
will be renamed to video.<md5-hash>.mp4
.
Templates
Templates are text files that contain references to assets or asset templates. They can be HTML, PHP, or in fact any other text file format.
Their encoding can be set on the Grunt file references in Gruntfile.js
.
Templates contain references to assets in the format {{image.jpg}}
or {{path/to/image.jpg}}
(the latter is based on the asset source path from the folder where Gruntfile.js
is.
These references will be replaced with the new file name of each asset. Please note that the file path will not be included, only the name.
This means that both of the above references will be replaced with image.<md5-hash>.jpg
in the templates.
Each template file will also be copied to the destination folder specified in the dest
property.
Asset templates
Asset templates are text files that contain references to assets or asset templates, just like templates. But asset templates may be cached by the browser, and we want to ensure that when they change, the browser always loads the latest version.
A good example of asset templates is CSS or JS files, which refer to assets (images, fonts, etc.), but are in turn referenced by HTML or PHP files.
Options
The following options may be specified in the Grunt config:
referencePrefix
Type: string
Default: '{{'
The prefix for references. Changing this will alter the reference format that grunt-kapocs
is searching for in templates and asset templates.
referenceSuffix
Type: string
Default: '}}'
The suffix for references. Changing this will alter the reference format that grunt-kapocs
is searching for in templates and asset templates.
temporaryFolder
Type: string
Default: 'tmp'
The temporary folder, where intermediate files may be placed. Asset templates are processed in two steps, so they will be copied here in the first step.
You may want to clean this folder using the grunt-contrib-clean
plugin after running grunt-kapocs
.
Building
This section explains how to build grunt-kapocs
when you wish to contribute bug fixes or new features to the project.
Prerequisites
- You'll need grunt-cli to have a local copy of Grunt for this project.
- You'll also need Bower to fetch the dependencies.
Building tasks/kapocs.js
- Clone the repo and enter its folder.
- Issue
npm install
to install the required NPM packages. - Issue
grunt update
to download dependencies and move them to thelib
folder.
- If you see any errors, resolve them by issuing
bower prune
,bower update
andbower install
manually and resolve conflicts. Once all conflicts are resolved, dogrunt update
again.
- Issue
grunt
to build.
Running tests
- Enter the
test
folder. - Issue
npm install
to install the required NPM packages. - Issue
grunt --force
. The--force
option is necessary as during testing the task throws some intentional errors.
Coding style
grunt-kapocs is written in TypeScript.
Indent with tabs, please.