Why Client Libraries are Useful in CQ

The Web used to be a simple place. All you needed to know to build a site was a little HTML and you were good to go. It didn’t take long for browser makers to introduce styles and JavaScript to their products, and eventually developers realized that they could use CSS and JavaScript to make a page look beautiful and feel dynamic. Not long after, it became common for websites to have a tag filled with references to stylesheet files and JavaScript libraries.

Knowing how messy that can make source code look, not to mention the toll on site performance, the creators of Adobe Experience Manager (AEM formerly Adobe CQ) implemented what is called the Client Library. Without the proper experience, it is a system that can get you into a lot of trouble.

At its basic level, the Client Library allows a developer to keep all of his or her stylesheets and JavaScript libraries organized in project folders in the CRX repository. On the front end, all these files are compiled into a single location referenced on the page. The browser only makes a single request, which cuts down on a lot of HTTP chatter.


As you can see from the image above, AEM provides a straightforward method for developers to take advantage of this feature. Simply place your JS and CSS files in a cq:ClientLibraryFolder with the appropriate js.txt and css.txt files so the Client Library knows which files to include.

Here’s an example from the Geometrixx Outdoors sample site pulled from /etc/designs/geometrixx-outdoors/:


The Drawback
As long as you’re the only developer working on a site and you’ve kept your files well-organized and tested, the Client Library really simplifies things for you. However, if you are brought in to help on a large site that has had several iterations of developers working on it, the Client Library can be a large, intimidating labyrinth. Luckily, there are a couple of tools to help track down that JavaScript bug that’s been driving you crazy.

The first and most simple tool is to simply append “debugclientlibraries=true” to the query string of your page. This will divide the Client Library scripts and stylesheets into their individual parts, so you more easily utilize your browser’s debugging suite to track issues.

The second tool provided by AEM is the Library Dump Tool. It can be reached at http://localhost:4502/libs/granite/ui/content/dumplibs.html?debugclientlibraries=true (where you replace localhost and the port based on your AEM environment). This tool lists out all the files available to the Client Library as well as each file’s dependencies—giving you a powerful tool for stamping out defects in your site.