studio-variable / kirby-assets-versioning
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
Type:kirby-plugin
pkg:composer/studio-variable/kirby-assets-versioning
Requires
- php: >=8.2
- getkirby/composer-installer: ^1.2
Requires (Dev)
- getkirby/cms: ^5.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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,
rsyncor a freshgit cloneresets 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Disables versioning when false, for example in a host-specific config. |
param | string | 'v' | Name of the URL parameter. Change it if it conflicts with another parameter. |
License
MIT License © 2026 Studio Variable