Registry / devops / eleventy-auto-cache-buster

eleventy-auto-cache-buster

library0.9.2jsnpmunverified

An Eleventy plugin that automatically adds content-hash based cache-busting query parameters (?v=...) to asset URLs (CSS, JS, images, etc.) with zero configuration. Currently at version 0.9.2, it requires Node >=20 and works with Eleventy. Unlike traditional cache-busting filters, it operates as a transform, meaning no template code changes are needed. It supports configurable hash algorithms, file extension filtering, glob patterns, and asynchronous processing. The plugin is lightweight and ideal for static sites built with Eleventy that need long-term caching without manual versioning.

devops

npm install eleventy-auto-cache-buster

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ELEVENTY-AUTO-CACH

eleventy-auto-cache-buster

devopsjavascriptv0.9.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

eleventyAutoCacheBuster

✓ import eleventyAutoCacheBuster from 'eleventy-auto-cache-buster'

✗ const eleventyAutoCacheBuster = require('eleventy-auto-cache-buster')

The package is ESM-only (exports default). In .eleventy.js (which runs in CommonJS by default), use dynamic import or set type:module. The require() call will fail unless you use a bundler or Node's --experimental-require-module flag.

eleventyAutoCacheBuster (require)

✓ const eleventyAutoCacheBuster = (await import('eleventy-auto-cache-buster')).default

✗ const eleventyAutoCacheBuster = require('eleventy-auto-cache-buster')

In .eleventy.js (CJS), the module is ESM-only. Use dynamic import() with .default, then pass to addPlugin. The correct pattern avoids the TypeError: eleventyAutoCacheBuster is not a function.

Plugin configuration object

✓ eleventyConfig.addPlugin(eleventyAutoCacheBuster, { enableLogging: true, hashTruncate: 8 })

✗ eleventyConfig.addPlugin(eleventyAutoCacheBuster, { hashTruncate: '8' })

The hashTruncate option expects a number (0 or lower disables truncation). Providing a string will not cause an error but may behave unexpectedly. Boolean options like enableLogging must be actual booleans.

Sets up the plugin with custom options including hash truncation, async processing, glob patterns, file extensions, and SHA-256 hashing. No template modifications needed.

// .eleventy.js import eleventyAutoCacheBuster from 'eleventy-auto-cache-buster'; export default function (eleventyConfig) { eleventyConfig.addPlugin(eleventyAutoCacheBuster, { enableLogging: true, hashTruncate: 8, runAsync: true, globstring: '**/*.{css,js}', globOptions: { nodir: true, ignore: ['node_modules/**'] }, extensions: ['css', 'js', 'png'], hashAlgorithm: 'sha256', }); } // Then build: npx @11ty/eleventy

Debug

Known issues

breakingThe package is ESM-only. Using require('eleventy-auto-cache-buster') in a CommonJS .eleventy.js file throws TypeError: eleventyAutoCacheBuster is not a function.

fix

Use dynamic import: const eleventyAutoCacheBuster = (await import('eleventy-auto-cache-buster')).default; or switch to ESM config.

affects: >=0.9.0

deprecatedVersion 0.9.2 is the latest but still below 1.0.0 – breaking changes may occur. The API is stable but not finalized.

fix

Pin to exact version in package.json to avoid unexpected changes.

affects: <1.0.0

gotchaThe hashTruncate option accepts a number; setting it to 0 or negative disables truncation. If you pass a string like '8', it will not truncate (treated as falsy).

fix

Always pass a number: hashTruncate: 8

affects: >=0.9.0

gotchaThe default globstring is '**/*' which may include node_modules if not overridden. This can cause very long build times or errors.

fix

Set globstring to a more specific pattern (e.g., '_site/**/*') or add ignore: ['node_modules/**'] to globOptions.

affects: >=0.0.0

gotchaThe plugin modifies HTML files in-place after build; if you have a custom output directory, ensure the files are within the glob pattern.

fix

Verify that globstring covers your output directory (default is Eleventy's output dir).

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: eleventyAutoCacheBuster is not a function

Using require() on an ESM-only module in a CommonJS context.

fix

Use dynamic import: const eleventyAutoCacheBuster = (await import('eleventy-auto-cache-buster')).default;

Error: ENOENT: no such file or directory, open '...' (in cache buster transform)

The glob pattern includes files that don't exist or the output directory is misconfigured.

fix

Ensure the globstring matches files in Eleventy's output (default: '_site'). Set globstring to '_site/**/*' or a similar path.

The plugin is not modifying my asset URLs

The plugin only processes HTML files in the output directory; assets must be linked in HTML and the glob must match them.

fix

Check that the globstring includes your output directory (e.g., '_site/**/*.html') and that asset tags use relative paths.

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Node.js version prior to 20 or missing --experimental-require-module flag.

fix

Upgrade to Node >=20 and ensure your .eleventy.js is treated as ESM or use dynamic import.

Upgrade

Version history

0.9.2latest on npm

Audit

Dependencies

@11ty/eleventyrequiredPeer dependency – the plugin adds transforms to Eleventy's build process.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/Denperidge/eleventy-auto-cache-buster ↗

packageeleventy-auto-cache-buster ↗

homepagehttps://github.com/Denperidge/eleventy-auto-cache-buster#readme ↗