Explore Client Libraries in AEM

Clientlibs or Client libraries in aem is 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.

In this tutorial i will cover all the basic functionalities Client Library Folder provides and how we can use them in our components. After completing this tutorial you will have a clear understanding about:-

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 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.traning (This name will be used to identify respective clientlibs folder)
  • Create a css and js folder parallel to clientlib folder, where our css and js files will be placed.
  • Create a js.txt and css.txt file parallel to cilenlibs folder.

create clientlibs aem

Lets 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 structure.

Client Library folder structure and its importance:-

Now if we look closely each node is used for specific purpose.

  • jcr:primaryType – The “clientlib” node must be of type cq:ClientLibraryFolder, so that aem understand that this is client lib folder.
  • categories – It is used to categorize or identify respective client library folder from where js and css files needs 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 send in the response.
    • If you want to include files from a particular clientlib folder then keep the category name unique.
      Note:- 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 location of clientlibs.
  • dependencies – when your client library files are dependent on some other files, you can use dependencies. For example if Clientlib A depends on Clientlib B which depends on Clientlib C, then all clientlibs A,B and C will be included in the page. The order in which they will be included is First C the B then A.
  • embed – AEM will merge all embedded clientlibs into the current clientlib. This is usually used for minimizing requests and for accessing clientlibs. Remember it might have size/speed issues if used frequently.  For example if Clientlib A embed Clientlib B which embed Clientlib C, then Clientlib A will be be loaded by embedding Clientlib B code. Remember Clientlib C will not be embedded in this case.

Things to notice about Child nodes js.txt and css.txt:-

  • A java script or css file will be generated by this name when we debug clientlibs, whereas minified file will be created by clientlib folder name.
  • Place each file name inside js or css.txt on separate line.
  • The first line should start with #base =[root], this refers to the path of folder that contains source file relative to TXT file.
    • For example if files are in same folder then write #base =.
    • But usually we put TXT file parallel to 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 file, if your clientlib only contains resources of one type only.

Note:- If we don’t add TXT files to client library folder then aem wont treat it as client library folder, because inside client library folder it looks for txt file to understand what are files it need 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:-

  • Login to Felix console and navigate to 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.

html library manager configurartion aem

  • Apart from minify 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.


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 browser?
    • Use ?debugClientLibs=true to load all js and css files separately without concatanation.
    • ?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
      Note:- Rebuild option will rebuild all css and js files available in aem including apps,etc,libs and other folders. It might take from 10-20 minutes for rebuild.

Add Client library in AEM or Include Client Library in HTL

Include both js and css file in single line

<sly data-sly-use.clientlib="/libs/granite/sightly/templates/clientlib.html"
    data-sly-call="${clientlib.all @ categories=['my-clientlib-category']}"/>

Include css file in single line

<sly data-sly-use.clientlib="/libs/granite/sightly/templates/clientlib.html"
    data-sly-call="${clientlib.css @ categories=['my-clientlib-category']}"/>

Include js file in single line

<sly data-sly-use.clientlib="/libs/granite/sightly/templates/clientlib.html"
    data-sly-call="${clientlib.js @ categories=['my-clientlib-category']}"/>

Looking for more info on client libraries in aem ?? Click Here

Spread the love

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.