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

> **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

```js
// 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

```xml
<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

```xml
<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

```html
<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:

```xml
<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:

```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.
