The Power of ClientLibs

The Power of ClientLibs

Client libraries (clientlibs) is a very interesting concept in AEM space. Clientlibs aim at organizing and optimizing serving of complex JavaScript and css code on the client side.

AEM provides client side library folders that store all the client side code in the respository. You can then organize them into categories and also define when and how each category of code is to be served to the client. The client-side library system then takes care of producing the correct links in your final webpage to load the correct code. The Main advantage of using clientlibs is that only the required clientside side code gets loaded leading to a performance gain. Also, the javascript and css code is better organized and that makes the debugging and maintenance of the code easier.

Using Clientlibs

  • Using Clientlibs
    All the clientside code including javascript and css files is stored under a node of type cq:ClientLibraryFolder. Its definition in CND notation is

[cq:ClientLibraryFolder] > sling:Folder
– dependencies (string) multiple
– categories (string) multiple
– embed (string) multiple
– channels (string) multiple

The node can be placed anywhere within /apps , /libs , /etc. The properties of the cq:ClientLibraryFolder are configured as follows:

  • categories: Identifies the categories into which the set of JS and/or CSS files within this cq:ClientLibraryFolder fall. The categories property, being multi-valued, allows a library folder to be part of more than one category (see below for how this may be useful).
  • dependencies: This is a list of other client library categories on which this library folder depends. For example, given two cq:ClientLibraryFolder nodes F and G, if a file in F requires another file in G in order to function properly, then at least one of the categories of G should be among the dependencies of F.
  • embed: Used to embed code from other libraries. If node F embeds nodes G and H, the resulting HTML will be a concetration of content from nodes G and H.

There are two ways by which you can add the clientlibrary in your code:

  • Add a cq:includeClientLib tag in the jsp code to add a link to the clientlibs. To reference the libraries, you use the value of the categories property of the cq:ClientLibrary node. or example, the /etc/clientlibs/foundation/jquery node is of type cq:ClientLibraryFolder with a categories property of value cq.jquery. The following code in a JSP file references the libraries:

    The generated HTML page contains the following code:

  • You include a clientlib using a piece of java code as well. The following java code adds a clientlib named cq.jquery to the jsp:


Before that, you need to add few more files under the clientlibrary node. They are two text files named js.txt and css.txt. js.txt contains entries for all the javascript code that needs to be included in the clientlibrary while css.txt contains entries for all the css related files. Note that you can add as many js and css files in the clientlibrary folder but only the files having entries in these two text files will eventually get added to the final clientlibrary code.

  • Debugging Clientlibs
    AEM provides several tools for debugging and testing client library folders. To trace the origin of embedded code, or to ensure that embedded client libraries are producing the expected results, you can see the names of the files that are being embedded at runtime. To see the file names, append the debugClientLibs=true parameter to the URL of your web page. The library that is generated contains @import statements instead of the embedded code.
    For listing all the clientlibs in use, the following url can be used:

    The above url provides the following options :

    • Output testing
    • Rebuilding all the clientlibs
    The HTML Library Manager service processes cq:ClientLibraryFolder tags and generates the libraries at runtime. They type of environment, development or production, determines how you should configure the service:
    • Increase security: Disable debugging
    • Improve performance: Remove whitespace and compress libraries.
    • Improve readability: Include whitespace and do not compress.

In the HTML library manager configuration available in system console, the options for minifying, g-zip, debug are available and this configuration can be modified based on the AEM environment being used.