Versioned ClientLibs in AEM

Versioned Clientlibs is a very nice add on provided by acs aem commons. It solves one of the key problem that most of the customer face now a days, to keep their css and js cached on client side for longer TTL(Time to Live). It allows css and javascript which is served by aem clientlibs to be cached at client side for very long time which in turns reduce the page load time of the website and improve performance.

Before versioned clientlibs , for normal client library it is advised to keep small TTL. Because once client libraries are modified or updated, it should be reflected at client browser. As the ttl were small, once it is expired new client libraries are fetched but at cost of page load time and inconsistent data until ttl expires.

In this tutorial we will see:-

How versioned client library works in aem:-

The main reason we use clientlibs is to concatenate all of our separate CSS files into one file and concatenate all of our JS files in another file to improveĀ page performance speed, by limiting the amount of network requests to the server. Apart from it in order to increase your website page performance speed we used to cache these client libraries on client browser with longer ttl.

But what happens when we modify our client libraries (js /css files), as it is cached end user will keep on viewing old/inconsistent data. To solve this problem acs commons has introduced versioned clientlibs in aem.

Versioned clientlibs uses Sling Rewriter to rewrite the client libraries generated by aem and append a unique MD5 value at end of the client library url. As after modification to client library, a new MD5 value is generated and appended to client library url this allows it to recache at client side. For example:-

Normal AEM Client Library URL:-Ā http://localhost:4502/etc.clientlibs/weretail/clientlibs/clientlib-base.js

Versioned Client Library URL:-Ā http://localhost:4502/etc.clientlibs/weretail/clientlibs/clientlib-base.f2e70583096c942b4b71351437bce842.js

Implement versioned client library in aem:-

In this tutorial , i am going to implement versioned clientlibs in AEM 6.4. Let’s take we retail example. By default versioned clientlibs are not implemented in we retail. Follow below steps to implement versioned clientlibs in aem :-

  • Login to http://localhost:4502/crx/de/index.jsp.
  • Navigate toĀ /apps/weretail/config and create a nt:unstructured folder by name it as rewriter.
  • Navigate toĀ /libs/cq/config/rewriter/default , copy the default node and paste it under your project config folder, in our case underĀ /apps/weretail/config.
  • Select default nodeĀ and addĀ versioned-clientlibs to transformer types as shown below.
  • You can add any number to transformers to your default node, transformers are used by sling rewriter to rewrite clientlibs into versioned clientlibs.
  • Click save All.

That’s it you have successfully configured versioned clientlibs in aem.

Note:- Minimum transformer required for creating version clientlibs areĀ transformerTypes=”[linkchecker,versioned-clientlibs]”/>,Ā You can remove other trasformer types if you don’t need them. As more transformer type you add it will take more time time for rewriting.

Note:- Rewrite should always be under conf node only, run mode specific rewriting is not available as of now.

Lets verify our versioned clientlibs:-

Important thing to note over here is, for loading your versioned clientlibs for first time. You need to restart your aem instance.

  • Navigate to Felix console–> Status –> Sling Rewriter http://localhost:4502/system/console/status-slingrewriter.check-rewrite-config-aem
  • Search for your resource pathĀ /apps/weretail/config/rewriter/default.
  • If you see your resource path under sling rewriter. It means your configuration is applied successfully.

Enable/Disable versioned clientlibs from Felix Console:-

Addition acs commons has provided an osgi configuration for enabling and disabling versioned clientlibs. Navigate to :-Ā Felix Console–> OSGI Configuration –> search forĀ Versioned Clientlibs Transformer Factory.Ā http://localhost:4502/system/console/configMgr/com.adobe.acs.commons.rewriter.impl.VersionedClientlibsTransformerFactory.


Apache Configuration for enable long TTL and enforcing Re caching of Clientlibs:-

Along with adding default sling rewriter in aem, you need to send correct header from your apache server. Add below configuration to your apache server to enable log TTl and re caching of versioned clientlibs.

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

Limitation of using Versioned Clientlibs in aem :-

As per acs commons documentation, currently sling rewriter doesn’t support below rewriting :-

  • 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, 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)

Know Issues :-

  • ForĀ Versioned ClientLibs: MD5 does not change when modifying an embedded clientlib category. For more details visit acs commons github.

ComparisonĀ between versioned Client Library and Normal Client Library:-

Comparison between versioned client library and normal AEM Client library:-

Versioned Client LibraryNormal Client Library
Longer TTLSmaller TTL
Recaching happens on the go, as each time clientlibs will have a new url due to unique MD5 value.Recaching happens only when TTL expires, user may see inconsisted data till that time
Sling rewriting works on transformers, more transformers you add more time it will take to rewrite and create versioned clientlibs.No sling rewriting is involved.


Spread the love

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.