Org Skills

Front-end pipeline and Site Themes

Supporting material for aem-frontend-development. Agents load it on demand; it ships inside the skill folder.

RawSource

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

  1. The front-end module is a plain Node project with a package.json.
  2. Cloud Manager runs npm run build. That script must exist.
  3. Whatever ends up in dist/ is what gets deployed and served as static files. Nothing outside dist ships.
  4. The name in package.json should identify the site it themes — for a site at /content/acme, acme-theme.
  5. The site is told which files to load through com.adobe.cq.wcm.core.components.config.HtmlPageItemsConfig, a Context-Aware Configuration under /conf that 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's dist build.
  • Remove the corresponding clientlib category from the page include, and add the files to HtmlPageItemsConfig instead.
  • Keep one source of truth. A theme deployed by the front-end pipeline and a clientlib copy of the same CSS in ui.apps means 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-builder runs 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 dist layout and HtmlPageItemsConfig contract 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.