Clientlib: CQ Static Resource Management

In this post I am going to cover a feature that is provided in CQ to manage static resources (js, css, images etc.). For every web application performance is an important factor that we usually ignore at first place and down the line it becomes a bottleneck for us. So, performance can be improved by considering various factors while designing a new application, few of them are listed below:

1) Web page size
A web page is composed of HTML markup, JS files, CSS files and images. We should try to keep page size as low as possible so that page is loaded quickly in browser.

2) Ajax calls v/s full page reload
There are many instances where it’s always better to make an Ajax call to hit the server and update a small area (HTML DOM) of page rather than reloading whole page.

3) Amount of data transfer between server and browser
When we make a call to service on server, the services should only return page/context specific data rather returning whole information/data. We can call server again (via Ajax calls) to fetch limited data and update page accordingly.

In this post I’ll try to show the benefit of using client libs feature to reduce the page size. Let’s consider a scenario where we have a web application built using CQ and it has multiple pages that are composed of many component. Each component needs a set of JS, CSS and images which might not be needed on other pages so, it does not make sense to load all those irrelevant resources on other pages where that component is not present.

For example we have a login page and a home page that user sees after successful login. The login page is composed of a login component (with a form) to enter username and password and we are using a jQuery validation plugin to validate form before submitting it to server. Once user is validated we redirect user to home page which does not have any form (i.e. we don’t need validation jQuery
plugin) on this page and there is no point in including validation plugin and we only need jQuery javascript file.

Login Page: needs jQuery and jQuery Validation plugin
Home Page: needs just jQuery

Normally, we include resource (like JS, CSS) in section of a page (in CQ it’s a template). If jQuery and jQuery validation plugin is included in head section of template then it’ll be included on every page no matters whether that page actually needs them or not and hence the page size is increased unnecessarily. There is better way to handle this in CQ and load the resources when they are actually needed and this is where CQ’s clientlib feature comes in to play.

What is client lib feature?
With client lib feature we can categorize every JS and CSS file as a library (with a specific name) and can include/import them in individual component or template (if it is used globally). For the time being consider this as java import feature. If on a page there are multiple component that needs the same library then CQ will make sure that the library is loaded only once. We can also define dependencies while creating clientlibs, e.g. jQuery validation plugin is dependent on base jQuery JS file.

How to define a client lib in CQ?
To define a client lib CQ follow below steps:

1) create a folder called clientlibs (by right clicking on designs folder) under /etc/designs (actually we can create this folder anywhere we want but, to keep it simple and consistent I am creating this under designs folder)

2) Create a new node under clientlibs folder called as jqvalidate with type as cq:ClientLibraryFolder (as shown below):

3) Copy/Put your JS (jq.validate-min-XXX.js) file in jqvalidate folder (we can also copy and css file to this folder if there is any).

4) Create a file js.txt in jqvalidate folder (also create another file css.txt if you have copied any css file in jqvalidate folder).

5) Add name of JS file (e.g. jq.validate-min-XXX.js) in js.txt (also add name of CSS file in css.txt) file and save it.

6) Click on jqvalidate folder node in crxde and open the Properties tab and update/add 2 new properties as shown below and save the node:
NOTE: both properties are of type String Array (String[])
a) categories: This is the name using which we’ll be referencing our jQuery validation client lib in our components and templates.
b) dependencies: Using this property we define the dependency of current library (in this case jQuery validation) on another client lib (in this case cq.jquery).

At this point we are done with creation of a validation library now, we’ll see how to use for developing components and templates.

How to use/import client lib?
To include a client lib in your component/template simply add following code/tag:

If you want to load multiple client libs then provide comma separated names against categories attribute in above tag e.g.


David Puerto said…
This was better than Adobe's documentation. Thanks for explaining how to link the resources by pointing to the css file inside the text file.
website design said…
I absolutely appreciated the articles material! Please keep it up writing about these postings, I’m able to more likely be subscribing subsequent!
website design
arun raj said…

i have a question here.

This issue is related to frequent building of client lib folder in adobe cq5.

Whenever i updating the code in js and css file, the changes are not reflected as soon as saving the related js and css file.

i have to do this url http://server:port//libs/granite/ui/content/dumplibs.rebuild.html.

After clicking the "rebuild libraries" button, then only my changes are updated in the html file.

Can i have to configure any file to bypass this process?


Popular posts from this blog

Sling Authentication

CQ Development - OSGi bundles and Components

Create an AEM (CQ) project using Maven

Multiple log files using log4j appender