Understanding Versioned Clientlibs and Dispatcher Cache Behavior

[mmasonWD]

We’re using versioned clientlibs in our project, and I’m wondering if something might be misconfigured—or if I’m misunderstanding how they’re intended to work.

The issue:
Whenever clientlib assets (CSS/JS) are updated and replicated, I go into the dispatcher and remove the old versioned clientlibs. However, this breaks all styles and scripts on the live site unless I also clear all cached content pages.

At first, I didn’t fully grasp what was happening, but it became clear that cached pages are still referencing the old versioned clientlibs. So when I remove those assets from the dispatcher, the cached pages are now pointing to files that no longer exist. Meanwhile, the new versioned clientlibs are present, but no pages in the cache are referencing them until the pages are recached from the publish instance.

This creates a challenge: clearing all cached content pages every time we update clientlibs feels inefficient.

So my question is, am I misunderstanding how versioned clientlibs are meant to function with the dispatcher cache, or is this just an inherent limitation of using versioned clientlibs in AEM?

[Vishal_Anand]

@mmasonWD There are couple of checkpoints you can quickly cross check.

• Browser cache. Lot of times clientlibs are cached at browser level so that can be the culprit.
• Akamai cache. Ensure Akamai cache is cleared if your application is leveraging that.

Best practices:

• Always prefer versioning your clientlibs with timestamp so that browser always makes fresh call to the clientlibs to avoid any caching if there are regular updates anticipated with UI.

[mmasonWD]

Hi, I am not sure this addresses the issue I am experiencing. The cached pages on my dispatcher are referencing the old versioned clientlibs. 

Referencing the new versioned clientlibs without having to completely clear out my entire dispatchers content pages is what I am hoping to have an answer for. Or like mentioned, if this is just a drawback of using the versioned clientlibs. 

[Vishal_Anand]

Yes. This is the drawback as cached pages will be referring to old versioned clientlibs unless they are explicitly purged.

[mmasonWD]

Thanks for confirming what I thought. I will wait to see if anyone has any other thoughts or recommendations. 

[DPrakashRaj]

Versioned client libs to work will still require to remove the page cache from the directory but not necessarily the clientlibs. As with versioned clientlibs will always have a new file name with the deployment but the page will still refrerence the old clientlibs as its cached so you need to delete the page cache so that the new page will referenced the new versioned clientlibs.

hope that helps.

[SantoshSai · Accepted solution]

Hi @mmasonWD,

Based on my experience working with versioned clientlibs, I’d like to share some insights that might clarify the behaviour you’re seeing.

How versioned clientlibs typically work

Versioned clientlibs append a unique hash or version suffix to asset URLs to help with cache busting. So when the CSS or JS changes, the URL changes as well. This is great for ensuring browsers fetch the latest assets.

Why you’re seeing issues with Dispatcher Cache

IMO, the main challenge here is that the dispatcher caches the full HTML pages, which include references to the old versioned clientlib URLs. So even after you’ve updated and replicated new clientlibs, the cached pages still point to the old asset URLs until those pages themselves get refreshed in the dispatcher cache.

When you delete the old clientlib assets without also clearing the cached pages that reference them, those pages break because they’re linking to files that no longer exist on the dispatcher.

Is this a misconfiguration or just how it works?

As per my understanding, this isn’t really a misconfiguration but an inherent behavior of how dispatcher caching interacts with versioned clientlibs.

The dispatcher treats pages and clientlib assets independently, so you need to make sure that when clientlibs change, the cached pages referencing those old versions are invalidated or cleared as well. Otherwise, you end up with stale pages referencing missing files.

Best practices from my experience

1. Coordinate cache invalidation of pages and assets: When deploying updated clientlibs, invalidate or clear the related cached pages simultaneously to avoid stale references.

2. Automate dispatcher cache purges: Use cache invalidation tools or scripts to clear both page caches and clientlib caches in sync.

3. Manage TTLs wisely: Set appropriate TTL (time-to-live) headers on dispatcher cache to help ensure pages don’t remain stale for too long.

4. Avoid purging only clientlibs: Because pages still reference those clientlibs, purging just assets breaks the page load.

[rahulp76079001]

Hi @mmasonWD ,

Its typically recommended not to modify clietlibs from the CRX/de, and have dispatcher flush configured on code deployment. So that you can avoid manual stuff like cache cleaning.

Generally, we cache content/clientlib files at the dispatcher level to improve performance of the site, but browsers are also created to provide extra performance by caching the clintlibs at the browser level. 

We can control and clear the at dispatcher whenever its required but browser cache is not in our control.

So, to deal with unexpected behaviour due to the cached content/clientlibs, a versioned clientlib was introduced, which means, clientlibs requests will be served along with an hshcode as a selector, and this selector will be updated each time whenever clientlib code is updated.

Why do we need to clear content after updating and replicating the clientlibs???

Clientlib URL with the hashcode selector is cached along with the page content, and new/updated clientlib code is available with a fresh hashcode selector, so to make it available we need to clear content from the dispatcher cache.

Thanks

[kautuk_sahni]

@mmasonWD Did you find the suggestions helpful? If you need more information, please let us know. If a response resolved your issue, kindly mark it as correct to help others in the future. Alternatively, if you discovered a solution on your own, we'd appreciate it if you could share it with the community. Thank you.