Builds Adobe Experience Manager Sites front-end code — the archetype ui.frontend webpack build, client libraries and categories, Style System CSS and design tokens, the responsive grid, JavaScript that survives the page editor, the Cloud Manager front-end pipeline and Site Themes, images and fonts, and Core Web Vitals on an AEM page.
When agents use itUse this whenever the user edits ui.frontend, webpack config or clientlib.config.js (aem-clientlib-generator), a clientlib .content.xml with categories, embed, dependencies or allowProxy, js.txt or css.txt, /etc.clientlibs URLs, async/defer include attributes, BEM styles for the Style System, aem-Grid or cq:responsive breakpoints, HtmlPageItemsConfig, the data layer or tag manager on an AEM page, aem-site-theme-builder, npm run watch, or asks why fonts 404 only on publish, why a carousel breaks the page editor, or how Core Image renditions affect LCP. For tests use `aem-testing`.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill aem-frontend-development -a github-copilot
# or with the org installer (adds .github/skills/aem-frontend-development):
npx -y github:AGCO-Global/org-skills add skill aem-frontend-development
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the aem-development-skills plugin, which bundles all AEM / Development skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install aem-development-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill aem-frontend-development -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill aem-frontend-development -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-frontend-development -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-frontend-development -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the aem-frontend-development folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
AEM front-end code runs in two very different places: a cached, CDN-fronted publish page, and an author page editor that swaps component DOM out from under you after every dialog save. Build one bundle per site, load it predictably, and write JavaScript that survives both without needing to know which one it is in.
allowProxy="{Boolean}true" on every library under /apps: publish denies reads on /apps, so the library is served from /etc.clientlibs/…. Reference fonts and images relative to the clientlib, never with an /apps/ path — that is why fonts 404 on publish and work on author.
Component libraries are embedded into the site library. Including them per component from HTL produces duplicate render-blocking requests and unstable ordering.
Include once, from the page component or the Core Page policy, using the Core Components clientlib template (it supports defer; the old Granite template does not).
Cloud Service serves content-hashed, long-cache clientlib URLs out of the box. On 6.5 you add a versioned-clientlib solution and the matching dispatcher cache headers.
Author-only code (dialog validators, editor extensions) belongs in cq.authoring.dialog or a component's extraClientlibs — never in the site bundle.
clientlib.config.js, the frontend-maven-plugin wiring with pinned Node, HtmlPageItemsConfig, ES modules and CSP notes are in references/clientlibs.md.
3. CSS, tokens and the grid
Core Components emit BEM (.cmp-teaser, .cmp-teaser__title). Follow the same scheme, one SCSS partial per component.
Style System classes land on the component wrapper, not the inner cmp- element:
Design tokens as CSS custom properties. Brands, themes and prefers-color-scheme swap token values, not selectors — a dark mode built from a second set of selectors doubles every future change.
Never depend on another component's markup order, on author-only wrappers, or on !important to beat Core CSS. Raise specificity with the block class.
The Layout Container's cq:responsive breakpoints and the generated grid SCSS must carry the same widths, or layout mode shows authors a layout visitors never get. The XML and SCSS contract is in references/clientlibs.md.
4. JavaScript that respects the editor
The page editor replaces a component's DOM after every dialog save, so a single DOMContentLoaded pass leaves the component dead until a reload. Initialise idempotently from markup, and re-scan on mutation — the pattern Core Components use:
const SEL = '[data-cmp-is="hero"]';
const init = el => { if (el.dataset.cmpInit) return; el.dataset.cmpInit = 'true'; /* wire up */ };
const scan = node => { if (node.nodeType === 1) { if (node.matches(SEL)) init(node);
node.querySelectorAll(SEL).forEach(init); } };
document.addEventListener('DOMContentLoaded', () => {
scan(document.body);
new MutationObserver(ms => ms.forEach(m => m.addedNodes.forEach(scan)))
.observe(document.body, { childList: true, subtree: true });
});
Read configuration from data-* attributes; no server values baked into inline scripts.
Disable behaviour that fights authors in edit mode — autoplay, scroll hijacking, modals on load, preventDefault on links. Emit a flag from HTL (data-wcmmode="${wcmmode.edit ? 'edit' : ''}" on <body>) instead of sniffing the URL or window.Granite.
Test with ?wcmmode=disabled on author and on publish; author adds wrappers and CSS that hide real bugs.
Analytics goes through the tag manager and a documented data-layer contract (adobeDataLayer events with named schemas), not hand-rolled vendor snippets in components.
5. Universal Editor and the front-end pipeline
Universal Editor on a Sites project needs little front-end work: current Core Components emit the data-aue-* instrumentation themselves, so an HTL page opens in the editor. Custom components emit the attributes themselves — see aem-universal-editor. A SPA is not required and SPA Editor is not an option for new work.
Front-end pipeline: a plain Node module whose npm run build produces a dist folder; Cloud Manager deploys the contents of dist as static files, and the site loads them through HtmlPageItemsConfig. A theme that deploys and changes nothing is almost always a missing HtmlPageItemsConfig entry. Full contract and the Site Theme workflow: references/front-end-pipeline.md.
6. Performance and accessibility
Images: Core Image v3 with widths configured in the policy so it emits srcset, plus web-optimized image delivery (or Dynamic Media where licensed). Never serve original DAM binaries or hand-built rendition paths. The LCP image loads eagerly with explicit dimensions; everything else lazily.
Fonts: self-host in clientlib resources, subset, font-display: swap, preload the one or two critical faces via HtmlPageItemsConfig.
Audit the tag manager payload — on most AEM sites it is the largest script and the main contributor to blocking time.
Measure on publish behind the CDN with field data (CrUX/RUM) alongside Lighthouse; author-mode numbers are meaningless.
Accessibility: visible focus styles, contrast checked for every Style System variant, prefers-reduced-motion, keyboard support for custom widgets, and no display:none on content screen readers need. Run axe against publish-mode renders, including the Core Components library pages.
7. Deliverable format
## Sources — SCSS/JS under ui.frontend (or the theme repo)
## Clientlib — clientlib.config.js / .content.xml changes: category, embed, allowProxy
## Include — HTL or HtmlPageItemsConfig change, with defer/async stated
## Policy — Style System group, label and class; Core Image widths if touched
## Verification — author edit mode, publish, each breakpoint, Lighthouse + axe result
Checklist
allowProxy set; no /apps/ URL in any CSS or JS
Component libraries embedded in the site library, not included per component
Scripts deferred; async only where ordering genuinely does not matter
JavaScript re-initialises after an author edit and is idempotent
Nothing autoplays, hijacks scroll or blocks clicks in edit mode
Style variants are Style System classes on the wrapper, no !important
cq:responsive breakpoints match the generated grid SCSS
LCP image is eager with dimensions; the rest lazy; srcset comes from the policy
Author-only code is not in the publish bundle
Generated clientlib folders are not hand-edited
Measured on publish behind the CDN, with axe run on the changed components
Anti-patterns
Hand-editing generated clientlib folders → change the source and rebuild; they are build output.
Missing allowProxy or an /apps/… URL in CSS → allowProxy="{Boolean}true" and clientlib-relative resource paths.
A clientlib include per component in HTL → embed the category into the site library.
async on libraries that depend on each other → defer, which preserves order.
JS that initialises once on load → idempotent init plus a MutationObserver re-scan.
Autoplay carousels and modals active in edit mode → gate them on a WCMMode flag emitted from HTL.
A new component for a colour variant → a Style System style group.
Grid breakpoints that differ from cq:responsive → one source of truth; layout mode must not lie to authors.
Serving original DAM binaries, or lazy-loading the hero → policy-driven srcset and eager LCP.
A pipeline theme plus a clientlib copy of the same CSS → pick one owner for the file.
Measuring performance on author → publish, behind the CDN, with field data.
Go deeper
references/clientlibs.md — clientlib.config.js, Maven/npm wiring, clientlib node properties, include templates, HtmlPageItemsConfig, ES modules and CSP, the grid breakpoint contract.
references/front-end-pipeline.md — front-end pipeline contract (npm run build → dist → HtmlPageItemsConfig), Site Themes, converting an archetype project, local development.
delivery-models.md in ../../architecture/aem-architecture/references/ — which model this front end belongs to.
Sibling skills: aem-component-development for HTL and dialogs, aem-universal-editor for in-place editing, aem-performance when a page is slow, aem-edge-delivery-services for EDS block development, aem-code-review for reviews.
---
name: aem-frontend-development
description: >
Builds Adobe Experience Manager Sites front-end code — the archetype ui.frontend webpack build, client libraries and categories, Style System CSS and design tokens, the responsive grid, JavaScript that survives the page editor, the Cloud Manager front-end pipeline and Site Themes, images and fonts, and Core Web Vitals on an AEM page. Use this whenever the user edits ui.frontend, webpack config or clientlib.config.js (aem-clientlib-generator), a clientlib .content.xml with categories, embed, dependencies or allowProxy, js.txt or css.txt, /etc.clientlibs URLs, async/defer include attributes, BEM styles for the Style System, aem-Grid or cq:responsive breakpoints, HtmlPageItemsConfig, the data layer or tag manager on an AEM page, aem-site-theme-builder, npm run watch, or asks why fonts 404 only on publish, why a carousel breaks the page editor, or how Core Image renditions affect LCP. For tests use `aem-testing`.
metadata:
technology: AEM
type: development
---
# AEM Front-end Development
> **Targets:** AEM as a Cloud Service 2026.x with the Maven AEM Project Archetype and platform Core Components; AEM 6.5 noted where different · **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/introduction/clientlibs
AEM front-end code runs in two very different places: a cached, CDN-fronted publish page, and an author page editor that swaps component DOM out from under you after every dialog save. Build one bundle per site, load it predictably, and write JavaScript that survives both without needing to know which one it is in.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Build for an archetype project | `ui.frontend` webpack → aem-clientlib-generator → `ui.apps` | Theme changes ship far more often than Java → add a **front-end pipeline** module |
| Low-code site from a Site Template | Site Theme repo + `aem-site-theme-builder` + front-end pipeline | Never mix a pipeline theme with a clientlib copy of the same CSS |
| New app-like experience | Headless or Edge Delivery Services with the Universal Editor | See `delivery-models.md` in `../../architecture/aem-architecture/references/` |
| New SPA Editor project | Not an option — deprecated with AEMaaCS 2025.01 and 6.5.23 | Only to maintain an existing SPA Editor site |
| Combining categories | `embed` (one request) | `dependencies` only when the other library must load as its own tag, first |
| Script loading | `defer` | `async` only for a library nothing else depends on — it destroys ordering |
| Visual variant | Style System modifier class on the wrapper | Never a new component, never `!important` against Core CSS |
| Number of bundles | One site CSS + one deferred site JS (+ a small vendor lib) | Split further only with a measurement showing the win |
| Where a `<head>` preload or third-party tag goes | `HtmlPageItemsConfig` under `/conf` | Hardcoding it in a page component makes it undeployable by site owners |
## 2. Client libraries
```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]"/>
```
- `allowProxy="{Boolean}true"` on every library under `/apps`: publish denies reads on `/apps`, so the library is served from `/etc.clientlibs/…`. Reference fonts and images **relative to the clientlib**, never with an `/apps/` path — that is why fonts 404 on publish and work on author.
- Component libraries are **embedded** into the site library. Including them per component from HTL produces duplicate render-blocking requests and unstable ordering.
- Include once, from the page component or the Core Page policy, using the Core Components clientlib template (it supports `defer`; the old Granite template does not).
- Cloud Service serves content-hashed, long-cache clientlib URLs out of the box. On 6.5 you add a versioned-clientlib solution and the matching dispatcher cache headers.
- Author-only code (dialog validators, editor extensions) belongs in `cq.authoring.dialog` or a component's `extraClientlibs` — never in the site bundle.
- `clientlib.config.js`, the `frontend-maven-plugin` wiring with pinned Node, `HtmlPageItemsConfig`, ES modules and CSP notes are in `references/clientlibs.md`.
## 3. CSS, tokens and the grid
- Core Components emit BEM (`.cmp-teaser`, `.cmp-teaser__title`). Follow the same scheme, one SCSS partial per component.
- Style System classes land on the **component wrapper**, not the inner `cmp-` element:
```scss
.cmp-teaser--dark .cmp-teaser__title { color: var(--color-text-inverse); }
```
- Design tokens as CSS custom properties. Brands, themes and `prefers-color-scheme` swap token *values*, not selectors — a dark mode built from a second set of selectors doubles every future change.
- Never depend on another component's markup order, on author-only wrappers, or on `!important` to beat Core CSS. Raise specificity with the block class.
- The Layout Container's `cq:responsive` breakpoints and the generated grid SCSS must carry the same widths, or layout mode shows authors a layout visitors never get. The XML and SCSS contract is in `references/clientlibs.md`.
## 4. JavaScript that respects the editor
The page editor replaces a component's DOM after every dialog save, so a single `DOMContentLoaded` pass leaves the component dead until a reload. Initialise idempotently from markup, and re-scan on mutation — the pattern Core Components use:
```js
const SEL = '[data-cmp-is="hero"]';
const init = el => { if (el.dataset.cmpInit) return; el.dataset.cmpInit = 'true'; /* wire up */ };
const scan = node => { if (node.nodeType === 1) { if (node.matches(SEL)) init(node);
node.querySelectorAll(SEL).forEach(init); } };
document.addEventListener('DOMContentLoaded', () => {
scan(document.body);
new MutationObserver(ms => ms.forEach(m => m.addedNodes.forEach(scan)))
.observe(document.body, { childList: true, subtree: true });
});
```
- Read configuration from `data-*` attributes; no server values baked into inline scripts.
- Disable behaviour that fights authors in edit mode — autoplay, scroll hijacking, modals on load, `preventDefault` on links. Emit a flag from HTL (`data-wcmmode="${wcmmode.edit ? 'edit' : ''}"` on `<body>`) instead of sniffing the URL or `window.Granite`.
- Test with `?wcmmode=disabled` on author **and** on publish; author adds wrappers and CSS that hide real bugs.
- Analytics goes through the tag manager and a documented data-layer contract (`adobeDataLayer` events with named schemas), not hand-rolled vendor snippets in components.
## 5. Universal Editor and the front-end pipeline
- **Universal Editor on a Sites project needs little front-end work**: current Core Components emit the `data-aue-*` instrumentation themselves, so an HTL page opens in the editor. Custom components emit the attributes themselves — see `aem-universal-editor`. A SPA is not required and SPA Editor is not an option for new work.
- **Front-end pipeline**: a plain Node module whose `npm run build` produces a `dist` folder; Cloud Manager deploys the contents of `dist` as static files, and the site loads them through `HtmlPageItemsConfig`. A theme that deploys and changes nothing is almost always a missing `HtmlPageItemsConfig` entry. Full contract and the Site Theme workflow: `references/front-end-pipeline.md`.
## 6. Performance and accessibility
- Images: Core Image v3 with widths configured in the **policy** so it emits `srcset`, plus web-optimized image delivery (or Dynamic Media where licensed). Never serve original DAM binaries or hand-built rendition paths. The LCP image loads eagerly with explicit dimensions; everything else lazily.
- Fonts: self-host in clientlib resources, subset, `font-display: swap`, preload the one or two critical faces via `HtmlPageItemsConfig`.
- Audit the tag manager payload — on most AEM sites it is the largest script and the main contributor to blocking time.
- Measure on **publish behind the CDN** with field data (CrUX/RUM) alongside Lighthouse; author-mode numbers are meaningless.
- Accessibility: visible focus styles, contrast checked for every Style System variant, `prefers-reduced-motion`, keyboard support for custom widgets, and no `display:none` on content screen readers need. Run axe against publish-mode renders, including the Core Components library pages.
## 7. Deliverable format
```
## Sources — SCSS/JS under ui.frontend (or the theme repo)
## Clientlib — clientlib.config.js / .content.xml changes: category, embed, allowProxy
## Include — HTL or HtmlPageItemsConfig change, with defer/async stated
## Policy — Style System group, label and class; Core Image widths if touched
## Verification — author edit mode, publish, each breakpoint, Lighthouse + axe result
```
## Checklist
- [ ] `allowProxy` set; no `/apps/` URL in any CSS or JS
- [ ] Component libraries embedded in the site library, not included per component
- [ ] Scripts deferred; `async` only where ordering genuinely does not matter
- [ ] JavaScript re-initialises after an author edit and is idempotent
- [ ] Nothing autoplays, hijacks scroll or blocks clicks in edit mode
- [ ] Style variants are Style System classes on the wrapper, no `!important`
- [ ] `cq:responsive` breakpoints match the generated grid SCSS
- [ ] LCP image is eager with dimensions; the rest lazy; `srcset` comes from the policy
- [ ] Author-only code is not in the publish bundle
- [ ] Generated clientlib folders are not hand-edited
- [ ] Measured on publish behind the CDN, with axe run on the changed components
## Anti-patterns
- **Hand-editing generated clientlib folders** → change the source and rebuild; they are build output.
- **Missing `allowProxy` or an `/apps/…` URL in CSS** → `allowProxy="{Boolean}true"` and clientlib-relative resource paths.
- **A clientlib include per component in HTL** → embed the category into the site library.
- **`async` on libraries that depend on each other** → `defer`, which preserves order.
- **JS that initialises once on load** → idempotent init plus a MutationObserver re-scan.
- **Autoplay carousels and modals active in edit mode** → gate them on a WCMMode flag emitted from HTL.
- **A new component for a colour variant** → a Style System style group.
- **Grid breakpoints that differ from `cq:responsive`** → one source of truth; layout mode must not lie to authors.
- **Serving original DAM binaries, or lazy-loading the hero** → policy-driven `srcset` and eager LCP.
- **A pipeline theme plus a clientlib copy of the same CSS** → pick one owner for the file.
- **Measuring performance on author** → publish, behind the CDN, with field data.
## Go deeper
- `references/clientlibs.md` — `clientlib.config.js`, Maven/npm wiring, clientlib node properties, include templates, `HtmlPageItemsConfig`, ES modules and CSP, the grid breakpoint contract.
- `references/front-end-pipeline.md` — front-end pipeline contract (`npm run build` → `dist` → `HtmlPageItemsConfig`), Site Themes, converting an archetype project, local development.
- `delivery-models.md` in `../../architecture/aem-architecture/references/` — which model this front end belongs to.
- Sibling skills: `aem-component-development` for HTL and dialogs, `aem-universal-editor` for in-place editing, `aem-performance` when a page is slow, `aem-edge-delivery-services` for EDS block development, `aem-code-review` for reviews.