Search by

studio-variable / kirby-assets-versioning

isUnknown

Append a content hash to the URLs of the CSS and JS files of a Kirby site, so browsers reload them as soon as they change

Package info

forge.studio-variable.com/studio-variable/kirby-assets-versioning.git

Homepage

Issues

Type:kirby-plugin

pkg:composer/studio-variable/kirby-assets-versioning

Statistics

Installs: 7

Dependents: 1

Suggesters: 0

v1.0.0 2026-11-14 11:27 UTC

This package is not auto-updated.

Last update: 2026-11-15 09:44:46 UTC


README

Append a content hash to the URLs of the CSS and JS files of a Kirby site, so browsers reload them as soon as they change, and keep them in cache as long as they don't. Works out of the box.

Installation • Usage • How it works • Configuration

Requirements

  • Kirby 5
  • PHP 8.2+

Installation

Composer (recommended)

The plugin is available on Packagist:

composer require studio-variable/kirby-assets-versioning

Manual installation

Download this repository and copy it to site/plugins/assets-versioning.

Usage

Nothing to change in your templates. Every file loaded with Kirby's css() and js() helpers gets a version parameter:

<?= css('assets/css/style.css') ?>
<?= js('assets/js/index.js', ['defer' => true]) ?>
<link href="https://example.com/assets/css/style.css?v=d73aad7d51b995f2" rel="stylesheet">
<script src="https://example.com/assets/js/index.js?v=1681c11542be71bd" defer></script>

@auto template assets are versioned too.

How it works

  • The version is a hash of the file's content, not of its modification date. Deploying with FTP, rsync or a fresh git clone resets the dates of every file, which would change every URL on each deploy. A content hash only changes when the file does.
  • Each file is hashed once per request with xxh3, which takes a fraction of a millisecond.
  • URLs that already have a query string get the parameter appended with &.
  • External URLs, and paths that don't match a file of the project, are left untouched.

Since a changed file always gets a new URL, you can safely serve your assets with long cache headers, for example in .htaccess:

<IfModule mod_headers.c>
  <FilesMatch "\.(css|js)$">
    Header set Cache-Control "public, max-age=31536000, immutable"
  </FilesMatch>
</IfModule>

Only add these headers if every CSS and JS file of the site goes through css() and js(): a file referenced by hand would no longer be refreshed.

Configuration

No option is required. Set them under the studio-variable.assets-versioning key of site/config/config.php if needed.

KeyTypeDefaultDescription
enabledbooltrueDisables versioning when false, for example in a host-specific config.
paramstring'v'Name of the URL parameter. Change it if it conflicts with another parameter.

License

MIT License © 2026 Studio Variable