Cache Busting via setting VERSION: -1 in xxyyzz.libraries.yml

The version key in libraries.yml is primarily used for cache-busting static assets like CSS and JavaScript files. By setting version: -1, Drupal will automatically generate a query string for the asset filenames, ensuring that the latest version of the assets is always served to users. This approach avoids relying on manual version increments and simplifies cache managemen

In the meanwhile, using -1 bypasses the default behavior where the version key might depend on Drupal core’s version (e.g., when set to VERSION). This ensures independence from core updates and avoids unintended conflicts or reliance on core versioning.

What is VERSION keyword in xxyyzz.libraries.yml for ? when should this keyword be changed ?

CHROMATIC’S BLOG

Introduction

We began to inspect how the file in question was attached to the page, which quickly led us to the *.libraries.yml file. A *.libraries.yml file will often look something like this:

1
2
3
4
5
6
7
8

xxyyzz:
  version: VERSION
  js:
    js/example.js: {}
  dependencies:
    - core/once
    - core/drupal.ajax
    - core/drupalSettings

Everything in there made sense, except the version key, which has always been a bit of a mystery to me. Values such as 1.x or VERSION are often found in the *.libraries.yml files for some core/contrib modules and on others the version key is omitted altogether. All of this led me to think it wasn’t very important. I couldn’t have been more wrong.

Library Version & Caching

The version key is used for cache-busting static assets that in many cases may have a TTL of one year or more (depending on your TTL settings). If you want users to see the latest version of your static assets, the version key could not be more important.

tl;dr If a static asset in a library file has changed, increase the library version number to ensure that the latest version of the asset is served.

Understanding “VERSION”

So now we understand what the version key does, however, the mystery VERSION string value remained. With a quick search through Drupal core I found the answer in \Drupal\Core\Asset\LibraryDiscoveryParser.php.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

if (isset($library['version'])) {
  // @todo Retrieve version of a non-core extension.
  if ($library['version'] === 'VERSION') {
    $library['version'] = \Drupal::VERSION;
  }
  // Remove 'v' prefix from external library versions.
  elseif (is_string($library['version']) && $library['version'][0] === 'v') {
    $library['version'] = substr($library['version'], 1);
  }
 }

Using VERSION will give you the full version string for the current version of Drupal core as stored in \Drupal::VERSION (e.g. 9.4.1). This is great if you are developing a core module, as this will increment when a new version of core is released. However, if you are working on a custom module, falling back on the version of Drupal Core doesn’t make much sense. Keep this in mind if you copy a core module to use as a basis for your custom module. Libraries in custom/contrib modules or themes should use a version string that increments in a way you control. In our case we went with 1.0.0 since this was the first version we were defining ourselves.

Note: There is a Drupal.org issue for making VERSION work in custom/contrib modules.

Hopefully this leaves you with a better understanding of why including version in your library definition is important, and perhaps the VERSION magic will soon be available to custom/contrib as well!

Drupal Answers

When should I change its value?

It is used as an identifier for your libraries. Just like any project/package is tagged in different versions. For eg: jQuery 3.5.1 is slightly different from 3.0.0. The difference could be anything, from API change, new features, bug fixes, etc. Thus we need a way to identify the changes that happened to our library we created. So that we can make some conscious decisions. Another example. Suppose there is a 3rd party js that is having issues with another library of a specific version. So during the install, we can check if the other library has library greater than required.

When should I change its value?

Ideally after every deployment if any change to the library has occurred. So what Drupal does is, it happens the version number to each file in that library when attaching that library to any page. For example: if my library has a css file called custom.css and the version number is say 1.0.0. So, the way it will get attached to the page will be like /path/to/theme/css/custom.css?v=1.0.0. This is so far ok. But ideally on prod environments there are reverse proxies which caches these files. Suppose if we make any new changes to these files and even if we clear the cache, the files will still be served from CDN, thus we also need to make sure if any change has happened on these files, it makes sense to also increase the library version number. Just as you would do with creating a new tag for a new release for any project.

If we give the version as VERSION. Then drupal sets its version = \Drupal::VERSION the current drupal core version.

–Ref: Drupal Answers

Reference

Alias:

  • disable theme cache
  • drupal theme cache
  • drupal theme javascript cache
  • drupal theme css cache
  • drupal js cache