ClientLibs and Front-End Pipelines in AEM

Ship small. Bundle smart. Let AEM do the heavy lifting without getting in your way.

I spent the week jumping between Adobe CQ code and front end tools, and it reminded me why AEM ClientLibs are still the simplest way to keep pages quick and tidy. Grunt just hit 0.4 and everyone is buzzing about streamlining builds. At the same time, we are still wrangling classic JSP components and a growing pile of jQuery and plugins. The trick is mixing both worlds so authors get speed and devs keep control.

ClientLibs give you a steady contract inside AEM. You declare a category, wire up a few files, and drop one tag in a JSP. Your pipeline can stay outside in Node or Maven land. The author does not care where you minified a file. They care that the page is fast and stable. So let ClientLibs be the public face, and let your build tools do the messy work backstage.

Deep dive 1. ClientLibs by example

A minimal client library lives under /etc/clientlibs and declares categories plus lists of source files. Keep it boring and it will pay you back.

/etc/clientlibs/app-site
  - js.txt
  - css.txt
  - categories (String[]) = ["app.site"]
  - dependencies (String[]) = ["cq.jquery"]
  /js
    app.js
    helpers/util.js
  /css
    styles.css

// js.txt
# base=js
app.js
helpers/util.js

// css.txt
# base=css
styles.css

Include it from a JSP and move on.

<%@ taglib uri="http://www.day.com/taglibs/cq/1.0" prefix="cq" %>
<cq:includeClientLib categories="app.site" />

Need to split code by page type. Use more categories like app.site.home or app.site.checkout. If a library depends on another, set the dependencies property so AEM orders them. Skip clever tricks. Keep files flat and small. Let your pipeline concatenate for you.

Deep dive 2. Minify, gzip, and debug

AEM ships with the Day CQ HTML Library Manager. Turn on minify and gzip for publish and leave debug off. Use run modes and keep the knobs in code so teams do not drift.

# /apps/myproj/config.publish/com.day.cq.widget.impl.HtmlLibraryManagerImpl.cfg
minify=true
gzip=true
debug=false
timing=false

On author, you might keep debug=true. You can also add ?debugClientLibs=true to a page to load individual files. That switch is gold when a single line breaks a page. Cache busting comes from last modified timestamps in AEM, so when you activate a new package the urls update.

Deep dive 3. Front end pipeline that feeds ClientLibs

Let Grunt build assets, then drop the output into your clientlib folders. LESS or Sass compiles outside AEM. RequireJS can bundle with rjs. The point is simple. ClientLibs are the delivery layer. Your pipeline is the factory.

// Gruntfile.js
module.exports = function(grunt) {
  grunt.initConfig({
    less: { dist: { files: { "build/css/styles.css": "src/less/styles.less" } } },
    requirejs: {
      compile: {
        options: {
          baseUrl: "src/js",
          name: "main",
          out: "build/js/app.js",
          optimize: "uglify2"
        }
      }
    },
    copy: {
      clientlib: {
        files: [
          {expand: true, cwd: "build/js", src: ["**/*.js"], dest: "ui.apps/src/main/content/jcr_root/etc/clientlibs/app-site/js"},
          {expand: true, cwd: "build/css", src: ["**/*.css"], dest: "ui.apps/src/main/content/jcr_root/etc/clientlibs/app-site/css"}
        ]
      }
    }
  });
  grunt.loadNpmTasks("grunt-contrib-less");
  grunt.loadNpmTasks("grunt-contrib-copy");
  grunt.loadNpmTasks("grunt-contrib-requirejs");
  grunt.registerTask("default", ["less", "requirejs", "copy:clientlib"]);
};

Package it with Maven so every build installs to a local author. This keeps front end and CQ in one flow.

<plugin>
  <groupId>com.day.jcr.vault</groupId>
  <artifactId>content-package-maven-plugin</artifactId>
  <version>0.0.24</version>
  <configuration>
    <filters>
      <filter>
        <root>/etc/clientlibs/app-site</root>
      </filter>
    </filters>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>install</goal>
      </goals>
    </execution>
  </executions>
</plugin>

If you prefer plain Sling install, keep the package step and push with your usual profile. The key is that the build writes to /etc/clientlibs/app-site and the JSP tag stays the same for authors.

Final thought. AEM ClientLibs are boring in the best way. They give you ordering, minify, gzip, and a clean include tag. Pair that with a small front end pipeline and life gets calmer. This week the web is churning with new tools and yet the steady path still wins. Keep your contracts tight, keep your bundles small, and let authors hit publish without fear.