# grunt-kapocs

> Cache busting grunt plugin. Works with any file type.

Latest version **2.0.4** (published 2016-04-21) · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install grunt-kapocs
pnpm add grunt-kapocs
yarn add grunt-kapocs
bun add grunt-kapocs
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 2.0.4 |
| Published | 2016-04-21 |
| First published | 2014-07-31 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.10.0 |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | András Parditka |
| Maintainers | andraaspar |
| Keywords | gruntplugin, cache busting, md5, hash, http caching |

## Links

- npm: https://www.npmjs.com/package/grunt-kapocs
- Repository: https://github.com/andraaspar/grunt-kapocs
- Issues: https://github.com/andraaspar/grunt-kapocs/issues
- npm.io page: https://npm.io/package/grunt-kapocs

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 2.0.4 (latest) — 2016-04-21
- 2.0.3 — 2014-10-14
- 2.0.2 — 2014-09-25
- 2.0.1 — 2014-09-24
- 2.0.0 — 2014-09-23
- 1.0.7 — 2014-09-12
- 1.0.6 — 2014-09-12
- 1.0.5 — 2014-08-31
- 1.0.4 — 2014-08-09
- 1.0.3 — 2014-08-02
- 1.0.2 — 2014-08-02
- 1.0.1 — 2014-07-31
- 1.0.0 — 2014-07-31

## README

# 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](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching).

## 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:

```js
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:

1. Copy all the assets from `src/assets` to `build`, appending a hash to their file names.
  * A file called `src/assets/images/image.jpg` will be copied to `build/images/image.<md5-hash>.jpg`.
2. Copy all the files from `src/asset_templates` to `build`, 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 to `build/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 with `image.<md5-hash>.jpg`.
3. Copy all the files from `src/templates` to `build`, expanding asset references in their contents.
  * A file called `src/templates/index.html` will be copied to `build/index.html`.
  * If a template contains `{{my-style.css}}` or `{{src/asset_templates/style/my-style.css}}`, each such reference will be replaced with `my-style.<md5-hash>.css`.

## Installing

You can install grunt-kapocs from NPM by doing:

```shell
npm install grunt-kapocs --save-dev
```

Don't forget to reference it in your `Gruntfile.js`:

```js
grunt.loadNpmTasks('grunt-kapocs');
```

## Using

Add the `kapocs` task to your Grunt config:

```js
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](http://gruntjs.com/configuring-tasks#files).

Each of these file references may also contain [grunt.file.copy options](http://gruntjs.com/api/grunt.file#grunt.file.copy). 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](https://www.npmjs.org/package/grunt-cli) to have a local copy of Grunt for this project.
* You'll also need [Bower](http://bower.io/) to fetch the dependencies.

### Building tasks/kapocs.js

1. Clone the repo and enter its folder.
2. Issue `npm install` to install the required NPM packages.
3. Issue `grunt update` to download dependencies and move them to the `lib` folder.
  * If you see any errors, resolve them by issuing `bower prune`, `bower update` and `bower install` manually and resolve conflicts.
  Once all conflicts are resolved, do `grunt update` again.
4. Issue `grunt` to build.

### Running tests

1. Enter the `test` folder.
2. Issue `npm install` to install the required NPM packages.
3. 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.

---
_Source: https://npm.io/package/grunt-kapocs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._