Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/developing-with-front-end-pipelines and https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/sites/administering/site-creation/enable-front-end-pipeline
Open this when deciding whether to split CSS/JS out of the full-stack pipeline, or when a theme deploys but the site does not pick it up.
What the front-end pipeline is for
It deploys static files only — the CSS, JS, fonts and images a site's theme needs — to the AEM distribution layer, without a Maven build and without touching Java or content. A theme change goes live in minutes instead of a full-stack deployment, which is the whole point: designers and front-end developers get their own cadence.
Use it when the front-end changes far more often than the back end, or when a Site Template–based site is themed by people who do not build the Java project. Keep everything in the full-stack pipeline when one team ships both and the extra pipeline is just more to keep in sync.
The contract
- The front-end module is a plain Node project with a
package.json. - Cloud Manager runs
npm run build. That script must exist. - Whatever ends up in
dist/is what gets deployed and served as static files. Nothing outsidedistships. - The
nameinpackage.jsonshould identify the site it themes — for a site at/content/acme,acme-theme. - The site is told which files to load through
com.adobe.cq.wcm.core.components.config.HtmlPageItemsConfig, a Context-Aware Configuration under/confthat lists the theme's CSS and JS. Adobe's "theme sources" download gives the folder structure with this already wired.
A theme that deploys successfully but changes nothing on the page is almost always item 5: the pipeline shipped the files, and no page is referencing them.
Converting an existing archetype project
- Move the sources that belong to the theme out of
ui.frontend's clientlib output path and into the front-end module'sdistbuild. - Remove the corresponding clientlib category from the page include, and add the files to
HtmlPageItemsConfiginstead. - Keep one source of truth. A theme deployed by the front-end pipeline and a clientlib copy of the same CSS in
ui.appsmeans two versions racing, and the one that wins depends on which pipeline ran last. - Component-scoped CSS that ships with a component (and its dialog JavaScript) stays in clientlibs. The front-end pipeline is for the site theme, not for everything front-end.
Site Themes and local development
- Site Template–based sites carry a theme repository: a plain npm project, no Java.
aem-site-theme-builderruns it locally (npm run live) by proxying a real AEM site and injecting the local theme, so you style against real content without a local AEM. - Deploy the same repository through the front-end pipeline.
- The theme's
distlayout andHtmlPageItemsConfigcontract are identical to the hand-rolled case above.
Local development for the classic archetype project
npm run watch # rebuilds and syncs clientlibs into a local SDK/Quickstart
npm start # webpack dev server with static markup, for isolated styling
Always verify against the local dispatcher SDK before pushing: clientlib proxying, cache headers and filters behave differently there than on the author instance you have been looking at, and /etc.clientlibs problems only appear once the dispatcher is in the path.
The AEM Core Components library pages (/content/core-components-examples) are a ready-made isolated rendering surface for checking a component's styling and accessibility without building a page.