Org Skills

Client libraries, the ui.frontend build and the responsive grid

Supporting material for aem-frontend-development. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/introduction/clientlibs and https://github.com/adobe/aem-clientlib-generator

Open this for the exact clientlib.config.js, clientlib node XML, include templates, the Maven/npm wiring or the grid breakpoint contract.

ui.frontend → clientlib generation

// ui.frontend/clientlib.config.js (excerpt)
module.exports = {
  context: __dirname,
  clientLibRoot: './../ui.apps/src/main/content/jcr_root/apps/acme/clientlibs',
  libs: [{
    name: 'clientlib-site',
    allowProxy: true,
    serializationFormat: 'xml',
    categories: ['acme.site'],
    dependencies: ['acme.dependencies'],
    cssProcessor: ['default:none', 'min:none'],   // webpack already minified
    jsProcessor:  ['default:none', 'min:none'],
    assets: {
      js:  ['dist/clientlib-site/*.js'],
      css: ['dist/clientlib-site/*.css'],
      resources: { cwd: 'dist/clientlib-site', files: ['**/*.*'], flatten: false,
                   ignore: ['**/*.js', '**/*.css'] }
    }
  }]
};

The generated clientlib folders (.content.xml, js.txt, css.txt and the copied assets) are build output. Hand-editing them is lost on the next build, and reviewing their diffs is noise — add them to the PR template's "generated" list.

Setting the processors to none matters: leaving the defaults makes AEM minify an already-minified bundle, which is slow at build time and occasionally breaks source maps.

Maven wiring

<plugin>
  <groupId>com.github.eirslett</groupId>
  <artifactId>frontend-maven-plugin</artifactId>
  <version>1.15.0</version>
  <configuration>
    <nodeVersion>v22.11.0</nodeVersion>
    <npmVersion>10.9.0</npmVersion>
    <workingDirectory>${project.basedir}</workingDirectory>
  </configuration>
  <executions>
    <execution><id>install node and npm</id><goals><goal>install-node-and-npm</goal></goals></execution>
    <execution><id>npm ci</id><goals><goal>npm</goal></goals>
      <configuration><arguments>ci</arguments></configuration></execution>
    <execution><id>npm run prod</id><goals><goal>npm</goal></goals>
      <configuration><arguments>run prod</arguments></configuration></execution>
  </executions>
</plugin>

Pin the Node and npm versions and commit the lockfile, so a local build, a CI build and a Cloud Manager build produce the same bundle. Check the Node versions Cloud Manager supports before bumping; an unsupported version fails the build step, not the tests.

Clientlib node

<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="cq:ClientLibraryFolder"
    allowProxy="{Boolean}true"
    categories="[acme.site]"
    embed="[acme.components.hero,acme.components.teaser]"
    dependencies="[acme.dependencies]"/>
Property Effect
categories The names other code includes. One per purpose, not per file
embed Concatenates those categories into this one — one request
dependencies Emits separate <script>/<link> tags before this one — one extra request each
allowProxy Serves the library from /etc.clientlibs/.... Required: publish denies reads under /apps

Resources (fonts, sprites, background images) are referenced relative to the clientlib, so they resolve through /etc.clientlibs. A URL containing /apps/ in CSS is a 403 on publish and works on author — the classic "fonts 404 only on publish" bug.

Including the libraries

<sly data-sly-use.clientlib="core/wcm/components/commons/v1/templates/clientlib.html">
  <sly data-sly-call="${clientlib.css @ categories='acme.site'}"/>
  <sly data-sly-call="${clientlib.js  @ categories='acme.site', defer=true}"/>
</sly>

The Core Components clientlib template supports async, defer, crossorigin, onload and type; the older /libs/granite/sightly/templates/clientlib.html does not. Prefer defer — async destroys ordering between libraries that depend on each other.

HtmlPageItemsConfig (com.adobe.cq.wcm.core.components.config.HtmlPageItemsConfig) is the Core Page v3 mechanism for adding items to <head> and the end of <body>: preloads, preconnects, third-party tags, and the theme files deployed by the front-end pipeline. It is a Context-Aware Configuration under /conf, so a site owner can change it without a deployment.

ES modules and CSP

  • Clientlibs can serve ES modules: set type="module" through the Core clientlib template's type attribute, and keep a bundled fallback only if the browser matrix requires one.
  • If the site sets a Content Security Policy with nonces, inline scripts injected by components will be blocked. Keep scripts in clientlibs, and route anything that must be inline through the mechanism that can carry the nonce.

Responsive grid

The Layout Container emits aem-Grid / aem-GridColumn--<breakpoint>--<n> classes. Breakpoints are declared on the template's cq:responsive node:

<cq:responsive jcr:primaryType="nt:unstructured">
  <breakpoints jcr:primaryType="nt:unstructured">
    <phone jcr:primaryType="nt:unstructured" title="Phone" width="{Long}650"/>
    <tablet jcr:primaryType="nt:unstructured" title="Tablet" width="{Long}1200"/>
  </breakpoints>
</cq:responsive>

and mirrored in the generated grid SCSS:

@include generate-grid-columns();                       // default (desktop)
@media (max-width: 1200px) { @include generate-grid-columns('tablet'); }
@media (max-width: 650px)  { @include generate-grid-columns('phone'); }

If the widths differ between the two, layout mode in the page editor shows authors a layout the visitor never gets. Keep the numbers in one place (SCSS variables generated from the same source, or a comment linking both) and check them together.

Never style .aem-GridColumn for looks — it belongs to layout mode. Use the component's own block class.