Understanding Versioned Clientlibs and Dispatcher Cache Behavior | Community
Skip to main content
M
mmasonWD
Level 3
June 20, 2025
Solved

Understanding Versioned Clientlibs and Dispatcher Cache Behavior

  • June 20, 2025
  • 5 replies
  • 938 views

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?

Best answer by SantoshSai

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.

5 replies

Vishal_Anand
Vishal_Anand
Level 4
June 20, 2025

@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.
    M
    mmasonWDAuthor
    Level 3
    June 20, 2025

    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
    Vishal_Anand
    Level 4
    June 20, 2025

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

    DPrakashRaj
    Community Advisor
    DPrakashRajCommunity Advisor
    Community Advisor
    June 22, 2025

    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
      Community Advisor
      SantoshSaiCommunity AdvisorAccepted solution
      Community Advisor
      June 22, 2025

      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.

      Santosh Sai
      rahulp76079001
      rahulp76079001
      Level 2
      June 23, 2025

      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
        Community Manager
        kautuk_sahniCommunity Manager
        Community Manager
        June 23, 2025

        @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.

        Kautuk Sahni
        Terms & ConditionsAccessibility statement

        Loading footer...