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.
- How to implement 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 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.
- 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 :-
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.
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:-
|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, 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.|