Frontend build integration (ui.frontend)
Purpose: Run a modern TS/Sass workflow whose output ships as clientlibs, with local dev against a running AEM.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| Frontend engineers | Daily workflow |
The pipeline
ui.frontend/src (TS, Sass, assets)
│ npm run build (webpack)
▼
ui.frontend/dist
│ aem-clientlib-generator (clientlib.config.js)
▼
ui.apps …/clientlibs/clientlib-site (+ clientlib-dependencies)
│ mvn install -PautoInstallSinglePackage
▼
AEM /apps → served via /etc.clientlibsclientlib.config.js maps dist files → clientlib folders, sets categories/embeds/allowProxy. It is the single source of truth binding the two worlds.
Faster inner loop
| Technique | What it gives |
|---|---|
npm run watch variants / aemfed / aemsync | Push changed files straight to AEM on save |
| webpack-dev-server with proxy to :4502 | Instant HMR for CSS/JS against real pages (proxy html from AEM, serve assets locally) |
| Storybook (or similar) on component markup copies | Pure-frontend iteration on complex UI before wiring into HTL |
The proxy approach is the sweet spot: author your HTL/deploy once, then iterate styles/behaviour at webpack speed.
Conventions
- All lint/format/test tooling lives in ui.frontend — standard npm scripts; CI runs them like any frontend repo.
- No source files directly in ui.apps clientlibs (generated only) — one-way flow, enforced in review.
- Vendor code →
clientlib-dependenciescategory; app code →clientlib-site; page-specific heavy widgets → their own lazy category included only where used. - TypeScript for anything non-trivial; the compiled output is what ships, AEM neither knows nor cares.