Versioning ClientLibs in AEM

Recently in a project I was working on, we had the need to cache our clientlibs and have them reliably recache every time there was a change. I looked around and found that there is an ACS AEM Commons tool made for just this purpose. In this post I’ll demonstrate how we went about using this tool to version our clientlibs.

The Versioned ClientLibs ACS AEM Commons feature uses a Sling rewriter to add an MD5 hash to the paths of your clientlibs, forcing them to recache after every modification. Typically Adobe Experience Manager will use the lastModified property to determine when to recache, however versioned-clientlibs is a more reliable approach.

To implement the versioned-clientlibs feature, simply copy the node from /libs/cq/config/rewriter/default to some path inside your application. In this example, we’ll choose /apps/acslibs/config/rewriter. For the most part this path is arbitrary, however the config node must be inside a four-level-deep path that ends in config/rewriter to work.

Your config file should be named versioned-clientlibs.xml and should look something like this:


Along with your config for the versioned-clientlibs, you should also copy down the default config node and make sure versioned-clientlibs is added to the transformTypes. Here’s an example of the content.xml for the default config:


If you want to validate whether your configuration was successful, you can check the Sling Rewriter tab in the OSGI Web Console (/system/console/status-slingrewriter). Under “Active Configurations” you should see a configuration section for the versioned-clientlibs.

Versioned ClientLibs


Along with the rewriter configuration, you’ll also need to configure Apache to send the right headers. Here’s an example of what the config should look like:

    SetEnvIf Request_URI "(\.min)?\.[a-f0-9]+\.js" long_expires=true
    SetEnvIf Request_URI "(\.min)?\.[a-f0-9]+\.css" long_expires=true
    Header set Cache-Control max-age=2592000 env=long_expires

That’s it. Now your clientlibs should recompile every time there’s a change to them.

It should be noted that per the ACS Adobe Experience Manager Commons documentation there are exceptions to which files this rewriter will support. These are the files this rewriter will NOT support:

  • URIs embedded in CSS or JavaScript, including: background-images, web fonts, etc.
  • Relative URIs, e.g., etc/clientlibs/mysite/styles.css
  • URIs including a scheme or protocol-relative location, e.g., and //
  • URIs to non-AEM HtmlClientLibrary resources, e.g., /etc/designs/mysite.css
  • Tags contained in conditional comments
  • Clientlibs included by JavaScript (e.g., when leveraging the property channels)

So if you’re looking for a way to reliably update your ClientLibs every time there is a change, this is a pretty simple approach.