underdot-bust

Gives Underdot templates a helper that links to a static file with a hash of its contents, so a browser reloads the file when it changes and keeps it cached otherwise.

Install

npm install underdot-bust

import type { Configuration } from 'underdot';
import { bust } from 'underdot-bust';
import { ejs } from 'underdot-ejs';

export default {
  plugins: [ejs(), bust()],
} satisfies Configuration;

The helper

bust(reference) returns the file's absolute URL followed by ?v= and eight hexadecimal characters of the SHA-256 of the bytes the build writes:

<link rel="stylesheet" href="<%= bust('/styles.css') %>">

<link rel="stylesheet" href="/styles.css?v=1a2b3c4d">

• A relative reference resolves against the file being rendered, and one starting with a slash from the source root.
• The hash is of the handled output, so a stylesheet compiled by Sass changes its link when the compiled CSS changes.
• A reference under an underscore is an error, since that file is never written.
• A reference no static file's output is at is an error.

Options

The plugin takes no options.

q-docs/specs/bust.md holds every rule the plugin commits to.