# Front-end pipeline and Site Themes

> **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

```bash
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.
