Client Libraries in AEM/Day CQ

Client Libraries in AEM
Clientlibs or Client libraries in aem are one of the most widely used features provided by Adobe, it allows us to not only manage our client-side resources like ( JavaScript, CSS, images, fonts, etc ) but also provide options to debug, minify, merge and gzip the client-side code.

How to use Clientlibs in AEM:
Using Client libraries in aem is very easy, we can create a client library folder either under apps, etc or libs but it is strongly recommended not to create client library folder under libs. This we will see later how we can restrict client library folder creation in aem.

Go to Crxde.
Select apps/project/<component>
Right, Click and create a new node.
Name: clientlib (You can use any name)
Type: cq:ClientLibraryFolder
Add categories property to clientlib node (Only mandatory property).
Name: categories
Type: String[]
Value: apps.aem.training (This name will be used to identify respective clientlibs folder)
Create a CSS and js folder parallel to the clientlib folder, where our CSS and js files will be placed.
Create a js.txt and css.txt file parallel to the cilenlibs folder.



Let's not go deeper into it as there are many tutorials available on how to create clientlibs but what we are interested in. Is the importance and role of creating such a structure.

Client Library folder structure and its importance:
Now if we look closely each node is used for specific purposes.
jcr:primaryType – The “clientlib” node must be of type cq:ClientLibraryFolder, so that aem understands that this is the client lib folder.
categories – It is used to categorize or identify the respective client library folder from where js and CSS files need to be included. Value of this field is a String array i.e you could use an existing name here, which means that when we include client library in component jsp file using a category name that is available in more than one client library folder, then js and CSS files of all such folder will be sent in the response.

If you want to include files from a particular clientlib folder then keep the category name unique.

Note: The categories' value is not a unique identifier. It can be assigned to multiple client lib folders.
It is advisable to preface the category value by ‘apps’ or ‘etc’ to specify the location of clientlibs.
dependencies: when your client library files are dependent on some other files, you can use dependencies.
embed: You may face a situation where at run time you want to embed code from a client library(Js & CSS) into another client library. Then you should use “embed” instead of “dependencies”. But it might have size/speed issues if used frequently.

Things to notice about Child nodes js.txt and css.txt:
A javascript or CSS file will be generated by this name when we debug clientlibs, whereas the minified file will be created by the clientlib folder name.
Place each file name inside js or css.txt on a separate line.
The first line should start with #base =[root], this refers to the path of the folder that contains source file relative to the TXT file.
For example, if files are in the same folder then write #base =.
But usually, we put the TXT file parallel to the client library folder. For example #base = js_mobile , where js_mobile contains js files.
You can skip either of the js.txt or css.txt files if your clientlib only contains resources of one type only.

Note: If we don’t add TXT files to the client library folder then aem won't treat it as client library folder because inside the client library folder it looks for txt file to understand what are files it needs to include in our component jsp.

How to Minify, Gzip, debug and restrict Client Libraries creation under libs:
To optimize aem performance, it is recommended to minify and gzip client libraries. Follow below steps to minify, gzip, debug and restrict client library folder creation in aem:

Log in to Felix console and navigate to the config manager.
Search for “Adobe Granite HTML Library Manager” (previously known as “Day CQ HTML Library Manager“).
Click on Adobe Granite HTML Library Manager below pop up will show up.

Apart from minifying and debug, you can also configure what should be the max-age for cookies, you can also view the time taken by each file to load by enabling timing.

NOTE: While working with client libraries in aem below are some points to notice, which can save your efforts and improve productivity.

Where are the generated client library files stored/cached in CQ?
You can view all generated clientlibs under /var/clientlibs
Is there a console where I can see all client libraries and their dependencies?
Yes, http://server/libs/cq/ui/content/dumplibs.html

How I can debug client library files in the browser?
Use ?debugClientLibs=true to load all js and CSS files separately without concatenation.
?debugClientLibs=true and CTRL+SHIFT+U gives you timing info

Is there a console available to invalidate and rebuild the ClientLibs?
Yes, http://localhost:4502/libs/granite/ui/content/dumplibs.rebuild.html