Front-End Adventures in AEM: Part I

What’s in a Clientlib?

Nobody writes about the Front-End and AEM…

The Client Library (Clientlib)

*note* - While the css.txt and js.txt files aren’t required, leaving them out of a clientlib can lead to weird side effects. For example, if Clientlib A has a dependency on Clientlib B, but has no js.txt or css.txt file, Clientlib B’s JS and CSS will NOT be included when Clientlib A is loaded on a page. However, if Clientlib B depends on Clientlib C and Clientlib B does have a js.txt and css.txt file, then Clientlib C’s JS and CSS will load normally in this situation. All this to say, it’s best to include these .txt files even if they’re empty to avoid these fringe situations.

A typical clientlib folder

*tip* - Do not use YUI for any clientlibs. YUI is a largely antiquated tool that can eat unknown CSS selectors/rules and can blow up on ES5 rules that are perfectly valid for your target browsers. I recommend using Google Closure Compiler for AEM core component dependencies and the “none” option for any dependencies handled by Webpack or Rollup. Instead, let your bundler handle the processing in those situations.

A clientlib’s .content.xml file

*tip* - For loading clientlibs in the editor, I’ve found it useful to have a single clientlib dedicated to the cq.authoring.dialog category and then specifying all the clientlibs I want loaded there in the dependencies array. This clientlib should only have a .content.xml file and empty css.txt/js.txt files. This prevents AEM from bundling all my clientlibs into a single large package for the editor and allows me to target the individual clientlibs via Hot Module Replacement.

*tip* - We should always minify and obfuscate (if possible) our code for production but where we do that depends on the clientlib’s purpose. For default, you should probably always specify none. This makes it easier to debug your code while in development. For minification, the answer is a bit more nuanced:

If your clientlib has an embed — Turn on Google Closure Compiler for JS with as much obfuscation as possible. For CSS, do not use YUI for anything. To reiterate, YUI is notorious for silently eating CSS selectors and rules.

If your clientlib does not have an embed — Consider turning off everything for both CSS and JS. Instead, have Webpack, Rollup, or whatever build process you use handle the minification and obfuscation for you. You’ll be able to achieve better results with something tailored for your code.

*tip* - Fingerprinting your clientlibs is a performance must. An alternative to longCacheKey for fingerprinting is Versioned Clientlibs from ACS AEM Commons. The advantage of this solution is that it will hash your JS file and CSS files independently even as a part of the same clientlib unlike with longCacheKey. However, it does require an additional dependency, only supports MD5 hashes as of this writing, and requires setup to help AEM determine the hash. longCacheKey is ultimately more flexible but would require you to have separate clientlibs for JS/CSS if you wanted to provide them separate values.

Resources Folder

@font-face {
font-family: "Open Sans";
src: url("resources/font.woff") format("woff");

*tip* - You can put any static file inside the resources folder, it doesn’t just have to be an asset for a clientlib to reference. For example, sometimes I’ll have large external SVG’s (like sprites) that I don’t want stored in the DAM because I rely on them in my components. Storing them in a clientlib’s resource folder gives me a consistent reference point that I can use anywhere.

Component Dependent Clientlibs




Christian, husband, father, web developer, gamer, scuba diver, @Vikings fan, and aquatic biology enthusiast. Soli Deo gloria!

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Benjamin Solum

Christian, husband, father, web developer, gamer, scuba diver, @Vikings fan, and aquatic biology enthusiast. Soli Deo gloria!