Skip to content
@staticbolt/core

Cache Bust Plugin

A staticbolt plugin that puts a content hash into the name of every referenced output file and rewrites the references to match. app.js becomes app.3f2a9c1b.js. The files can then be served with a long cache lifetime, and a new build is always fetched.

Installation

The plugin ships as part of @staticbolt/core. You do not need to install anything else.

Usage

In your .staticbolt.ts configuration file, before writeFilesPlugin. It runs at write time, once every transform is done and right before the files hit the disk:

import { defineConfig } from "@staticbolt/core";
import { cacheBustPlugin, writeFilesPlugin } from "@staticbolt/core/plugins";


export default defineConfig({
  plugins: [
    // ...
    cacheBustPlugin(),
    writeFilesPlugin({ clean: true }),
  ],
});

The plugin only runs during production builds and has no effect in development.

What gets renamed

Every output file that some page, stylesheet, script or bundled package references: scripts, styles, SVGs, web manifests, the package bundles, the images and fonts that the copy assets plugin registers, and the images that the convert images plugin converts. HTML pages keep their names, since those are the URLs people share. Files nothing references are left alone.

The hash covers the file and everything it references. Change a stylesheet deep in an @import chain, and every stylesheet above it is renamed. The page picks up the new names. A converted image is hashed on its original, because the conversion runs after the build. Changing only the quality or the preset does not rename it.

The bundle packages plugin already hashes the assets it bundles out of a package. Those are left alone.

Plugin Options

include

  • Type: string[]
  • Default: ["**/*"]

Glob patterns of the output files to version, relative to the output directory.

exclude

  • Type: string[]
  • Default: []

Glob patterns of the output files to leave alone.

cacheBustPlugin({
  exclude: ["manifest.json", "**/*.pdf"],
});

hashLength

  • Type: number
  • Default: 8

How many characters of the content hash go into the file name.