Tutorial on ClientLibs in AEM

Versioned Clientlibs is a very nice add on provided by ACS AEM commons. It solves one of the key problems that most of the customer face nowadays, 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 the client-side for a very long time which in turn reduces the page load time of the website and improves 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 in the client browser. As the TTL were small, once it is expired new client libraries are fetched but at the cost of page load time and inconsistent data until TTL expires.

In this tutorial, we will see:-

·       How the versioned client library works in aem.

·       How to implement a versioned client library in aem.

·       Comparison between versioned client library and normal client library.

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 number 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 the client browser with longer TTL.

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

Versioned clientlibs use Sling Rewriter to rewrite the client libraries generated by aem and append a unique MD5 value at the end of the client library URL. After modification to the client library, a new MD5 value is generated and appended to the client library URL this allows it to recache at the 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 the 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 naming it as a 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 the default node and add versioned-clientlibs to the 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 transformer types if you don’t need them. As more transformer types you add it will take more time for rewriting.

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

Let's verify our versioned clientlibs:-

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

·       Navigate to Felix console–> Status –> Sling Rewriter http://localhost:4502/system/console/status-slingrewriter.

·       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:-

Additional acs commons have 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 a default sling rewriter in aem, you need to send the correct header from your apache server. Add below configuration to your apache server to enable log TTL and re caching of versioned clientlibs.

1 2 3

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. http://example.com/etc/clientlibs/mysite/styles.css and //example.com/etc/clientlibs/mysite/styles.css

·       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 Library	Normal Client Library
Longer TTL	Smaller 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, the user may see inconsistent 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.