ZetCode

Gulp cache busting

last modified November 15, 2026

In this article we add content hashes to file names with Gulp 5. The gulp-rev plugin renames style.css to style-c2442b7db7.css, and gulp-rev-rewrite updates the references in HTML and CSS, so browsers always get the current version of a file.

Cache busting

Browsers keep copies of stylesheets, scripts and images. For performance we want the copies to live as long as possible, for a year if possible, but then a visitor does not see a new version of a file, because the browser does not ask for it. The solution is to make the name of the file depend on its content: when the content changes, the name changes, and the browser has to fetch the new file; while the content is the same, the old name and the cached copy are used. This is called cache busting or revisioning.

The work has two parts. First, the files get a hash of their content in the name; the plugin gulp-rev does this and creates a manifest, a JSON file that maps the old names to the new ones. Second, every place that refers to a file must use the new name; the gulp-rev-rewrite plugin finds the references in HTML and CSS and replaces them with the help of the manifest.

Installing the project

We create a project and install Gulp, the two plugins and del for cleaning the output. Both plugins are ES modules, so the project is an ES module project and the gulpfile is an ES module, as in the ESM gulpfile tutorial.

$ mkdir gulp-rev
$ cd gulp-rev
$ npm init -y
$ npm pkg set type=module
$ npm i -D gulp gulp-rev gulp-rev-rewrite del
$ mkdir -p src/css src/js src/img

The example project

The page uses a stylesheet, a script and an SVG image, and the stylesheet uses the image as a background, so the image is referenced from two files.

src/index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Cache busting</title>
    <link rel="stylesheet" href="css/style.css">
</head>
<body>
    <h1>Hello</h1>
    <img src="img/logo.svg" alt="Logo">
    <script src="js/app.js"></script>
</body>
</html>
src/css/style.css
body {
    margin: 0;
    background: url(../img/logo.svg) no-repeat;
}
h1 { color: #336699; }
src/js/app.js
console.log('app started');
src/img/logo.svg
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><circle cx="50" cy="50" r="40" fill="#ff0000"/></svg>

The files are in src and the result goes to dist.

The gulpfile

The gulpfile has four tasks, which run in series. The order is important and we explain it in the following sections.

gulpfile.mjs
import { src, dest, series } from 'gulp';
import { deleteAsync } from 'del';
import rev from 'gulp-rev';
import revRewrite from 'gulp-rev-rewrite';
import fs from 'node:fs';

const manifestOptions = { base: 'dist', merge: true };

function readManifest() {

    return fs.readFileSync('dist/rev-manifest.json');
}

export function clean() {

    return deleteAsync('dist');
}

export function images() {

    return src('src/img/**/*', { base: 'src', encoding: false })
        .pipe(rev())
        .pipe(dest('dist'))
        .pipe(rev.manifest('dist/rev-manifest.json', manifestOptions))
        .pipe(dest('dist'));
}

export function code() {

    return src('src/{css,js}/**/*', { base: 'src' })
        .pipe(revRewrite({ manifest: readManifest() }))
        .pipe(rev())
        .pipe(dest('dist'))
        .pipe(rev.manifest('dist/rev-manifest.json', manifestOptions))
        .pipe(dest('dist'));
}

export function pages() {

    return src('src/*.html')
        .pipe(revRewrite({ manifest: readManifest() }))
        .pipe(dest('dist'));
}

export const build = series(clean, images, code, pages);

The build task cleans the output, then processes the images, then the stylesheets and scripts, and finally the pages. See the Gulp series and parallel tutorial for series and the Gulp clean tutorial for the clean task.

Hashing the images

The images task passes the files through rev(), which appends a hash of the content to the name, and writes them. The base option of src keeps the directory img in the paths, and encoding: false keeps binary files intact, as in the Gulp images tutorial. Then rev.manifest() turns the stream of renamed files into the manifest, which dest writes. The merge option adds the entries to an existing manifest instead of replacing it, so that the next tasks can add their files; base is the directory of the manifest.

export function images() {

    return src('src/img/**/*', { base: 'src', encoding: false })
        .pipe(rev())
        .pipe(dest('dist'))
        .pipe(rev.manifest('dist/rev-manifest.json', manifestOptions))
        .pipe(dest('dist'));
}

The task writes the renamed image and the manifest with one entry.

$ npx gulp clean --silent
$ npx gulp images --silent
$ ls dist/img
logo-066aa8739a.svg
$ cat dist/rev-manifest.json
{
  "img/logo.svg": "img/logo-066aa8739a.svg"
}

Hashing styles and scripts

The images are processed first, because the stylesheet refers to one of them and the hash of the stylesheet depends on its content, including the references. The code task first runs revRewrite with the manifest that has the images, so that url(../img/logo.svg) becomes url(../img/logo-066aa8739a.svg), and then rev() hashes the changed stylesheet; if we hashed it first, the hash would not change when the image does, and a cached stylesheet would point to an old image. The task adds its files to the manifest.

export function code() {

    return src('src/{css,js}/**/*', { base: 'src' })
        .pipe(revRewrite({ manifest: readManifest() }))
        .pipe(rev())
        .pipe(dest('dist'))
        .pipe(rev.manifest('dist/rev-manifest.json', manifestOptions))
        .pipe(dest('dist'));
}

The manifest is read when the task starts, from the file the previous task wrote. It now has all three files, and the stylesheet in the output refers to the hashed name of the image.

$ npx gulp code --silent
$ ls dist/css dist/js
dist/css:
style-c2442b7db7.css

dist/js:
app-e54f5f736a.js
$ cat dist/rev-manifest.json
{
  "css/style.css": "css/style-c2442b7db7.css",
  "img/logo.svg": "img/logo-066aa8739a.svg",
  "js/app.js": "js/app-e54f5f736a.js"
}
$ cat dist/css/style-*.css
body {
    margin: 0;
    background: url(../img/logo-066aa8739a.svg) no-repeat;
}
h1 { color: #336699; }

Rewriting the pages

The last task, pages, reads the HTML, rewrites the references with the complete manifest and writes the result. The HTML files themselves are not hashed, because they are the entry points that users type in or follow from links; they should be served with a short cache time. The plugin rewrites the files with the extensions .html, .css, .js and .hbs by default; the replaceInExtensions option changes the list.

export function pages() {

    return src('src/*.html')
        .pipe(revRewrite({ manifest: readManifest() }))
        .pipe(dest('dist'));
}

The page now refers to the three hashed files. The whole build is run by the build task.

$ npx gulp build --silent
$ find dist -type f | sort
dist/css/style-c2442b7db7.css
dist/img/logo-066aa8739a.svg
dist/index.html
dist/js/app-e54f5f736a.js
dist/rev-manifest.json
$ grep -E "href|src=" dist/index.html
    <link rel="stylesheet" href="css/style-c2442b7db7.css">
    <img src="img/logo-066aa8739a.svg" alt="Logo">
    <script src="js/app-e54f5f736a.js"></script>

Changing a file

The hash depends on the content only, so a rebuild of unchanged files gives the same names, and the files in the cache of the browsers stay valid. We append a comment to the SVG image and build again. The name of the image changes, and so does the name of the stylesheet, because its content changed when the reference was rewritten; the script, which did not change, keeps its name. Visitors download the new image and stylesheet, and the cached script is reused.

$ cp dist/rev-manifest.json before.json
$ echo "<!-- version 2 -->" >> src/img/logo.svg
$ npx gulp build --silent
$ diff before.json dist/rev-manifest.json
2,3c2,3
<   "css/style.css": "css/style-c2442b7db7.css",
<   "img/logo.svg": "img/logo-066aa8739a.svg",
---
>   "css/style.css": "css/style-cd9379e5d2.css",
>   "img/logo.svg": "img/logo-aee90cc011.svg",

Serving the files

The benefit comes from the server configuration. Files with a hash in the name never change, so they can be cached for a year and marked as immutable, with a header such as Cache-Control: public, max-age=31536000, immutable, while the HTML files get a short cache time or must be revalidated. Without a long cache time, the hashes only add complexity. The hashes can also be added together with the minification described in the Gulp Terser and Gulp clean-css tutorials: the minifier is placed before rev(), so the hash is computed from the final content.

Source

gulp-rev on npm, gulp-rev-rewrite on npm, HTTP caching on MDN

In this article we have added content hashes to file names with Gulp 5: we used gulp-rev and a merged manifest, rewrote the references in stylesheets and pages with gulp-rev-rewrite, and saw how a change of one file changes only the names that depend on it. See also the Gulp src and dest and Gulp conditional pipelines tutorials.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.