Session 7 — Client libraries & frontend workflow
Purpose: Ship CSS/JS the AEM way: clientlib categories, dependencies, embedding, and integrating a modern frontend build.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| Frontend engineers | Your bundling story in AEM |
ClientLibs = named bundles in the repo
A client library folder (cq:ClientLibraryFolder) declares a category (its bundle name), optional dependencies (loaded before, kept separate) and embeds (inlined into this bundle).
/apps/phi-academy/clientlibs/
├── clientlib-base/ categories=[phi.base] embeds component CSS
│ ├── css.txt ← ordered list of CSS sources
│ └── js.txt
├── clientlib-site/ categories=[phi.site] dependencies=[phi.base]
└── clientlib-dependencies/ categories=[phi.dependencies] (vendor)| ClientLib concept | Frontend-world equivalent |
|---|---|
| category | Named webpack entry/bundle |
| dependencies | External chunk loaded first |
| embed | Merged into the bundle (like importing into one entry) |
| css.txt / js.txt | Ordered import manifest |
| allowProxy | Exposes /apps libs via /etc.clientlibs to publish safely |
Pages include bundles by category in HTL:
<sly data-sly-use.clientlib="/libs/granite/sightly/templates/clientlib.html"
data-sly-call="${clientlib.all @ categories='phi.site'}"></sly>Modern build integration
The archetype's ui.frontend module is a standard webpack/TS project whose build output is copied into a clientlib by the aem-clientlib-generator. You keep your familiar workflow (npm, TS, Sass, linting); AEM only sees the compiled artefact.
ui.frontend (npm run build) ──▶ dist/ ──clientlib-generator──▶ ui.apps clientlib ──mvn──▶ AEMRules of thumb
- One site-wide category (
phi.site) embedding per-component libs — fewer requests, dispatcher-friendly. - Component CSS lives with the component, embedded into the base lib — deleting the component deletes its CSS.
- Long-term caching: enable clientlib longCacheKey/versioned clientlibs so cache-busting is automatic on release.
- Never hand-edit generated clientlibs; treat
ui.frontendas the source of truth.