Problem/Motivation

Using version: VERSION in a contrib or custom module's libraries.yml file can lead to significant caching issues, particularly when you need to update your module's assets frequently.

When you specify version: VERSION in your libraries.yml file, Drupal uses the core version number (like 9.4.1) as a query string parameter for your CSS and JavaScript files. This creates URLs like example.js?v=9.4.1 for your assets.

The problem with this approach is that these assets will be cached in browsers based on this version string, which only changes when Drupal core itself is updated. This means:

  1. Your module's asset changes won't be reflected until a core update occurs
  2. Users may continue to see outdated CSS or JavaScript even after you've deployed updates
  3. Manual browser cache clearing becomes necessary for users to see changes

This is particularly problematic when using edge caching or CDN caching, as it becomes difficult to invalidate the cache when you make changes to your assets. Even running drush cr won't help in this situation because the version string remains tied to the core version.

Steps to reproduce

This can produce various problems after an update, as the old versions of assets might be loaded for users who have those cached. The only way to currently fix those to clear the browser cache.

Proposed resolution

Remove the version: VERSION lines from libraries.yml. By doing this, Drupal will use an automatically generated query string added to filenames. From the code documentation:

The string changes on every update or full cache flush, forcing browsers to load a new copy of the files as the URL changed.

See: web/core/lib/Drupal/Core/Asset/JsCollectionRenderer.php:62

The other option is to explicitly set the module's version on these lines and keep track of it when the version number changes/the asset is updated.

Issue fork facets-3501351

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

prem suthar created an issue. See original summary.

nidhish’s picture

Assigned: prem suthar » nidhish

prem suthar’s picture

Status: Active » Needs review
strykaizer’s picture

It looks like the best solution would be to have #2205027: VERSION in library declarations does not work for contributed/custom modules commited in core, so we can cache our assets as best as possible.

prem suthar’s picture

You're absolutely right. Having #2205027: VERSION in library declarations resolved and committed in core would significantly enhance our ability to cache assets effectively. It would also bring more consistency and reliability when handling contributed and custom modules. This improvement could save both development time and resources while improving site performance. Let’s hope it gets prioritized soon!

mxr576’s picture

Issue summary: View changes

It looks like the best solution would be to have #2205027: VERSION in library declarations does not work for contributed/custom modules commited in core, so we can cache our assets as best as possible.

It could be, but until that is resolved, the current solution with version: VERSION leads to cache invalidation issues at client side and CDN level when only this module is updated.

So heavy +1 on removing this constant usage for now and let Drupal to calculate the version of the asset based on the hash of the file for now.

See also the warning on https://www.drupal.org/docs/develop/theming-drupal/adding-assets-css-js-...

hosterholz’s picture

Status: Needs review » Reviewed & tested by the community

I agree with nidhish and mxr576. Right now version: VERSION breaks cache busting and should be considered a bug. The library version should be changed every time a script changed is released or it should be removed.
I reviewed and tested MR!276.

strykaizer’s picture

Status: Reviewed & tested by the community » Fixed

Now that this issue is closed, please review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, please credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.