Migration Guide
AEM to headless, without leaving Adobe.
For most enterprises this isn't ripping out Adobe Experience Manager. It's decoupling it — keeping the authoring workflow, the DAM, and the approval process, and replacing only the rendering layer that ties content to a single web page.
This guide covers what that decoupling actually involves: the content model, the SEO trade-off nobody mentions upfront, the integrations AEM ran invisibly, and what breaks the first time content ships through an API instead of a page.
Scope
Who this guide is for — and who should stay on AEM Sites.
Headless is a rendering-architecture decision, not an upgrade. It pays back when more than one surface needs the same content.
This applies when
- Content needs to reach more than one surface — a storefront, a native app, a kiosk — from one source.
- Commerce already runs on a separate engine (Salesforce Commerce Cloud, Shopify) and AEM is content-only.
- Engineering wants ownership of rendering and performance instead of inheriting AEM's dispatcher stack.
Stay on AEM Sites if
- A single web surface is the only channel, with no near-term plan to add a second.
- The authoring team is deeply invested in in-context WYSIWYG page editing, with no engineering bandwidth to build a new renderer.
- Current SEO and performance are already strong and there is no multi-channel need driving the change.
See Legacy Modernization for modernizing the estate in place instead.
Content-model mapping
Five things that change shape, one that mostly doesn't.
Components & templates → content model
Templates stop being page containers and become typed Content Fragment Models, reused across every channel instead of rebuilt per page. A component that only ever rendered HTML now has to describe its data shape, not its markup — a hero banner becomes a model with a headline field and an image reference, not a JSP include.
DAM & renditions → Assets HTTP API
Images and renditions decouple from the page renderer. Responsive image sets and dynamic-media crops that the dispatcher handled implicitly need a rebuilt rendition strategy in front of the Assets HTTP API, or every consuming channel — web and native alike — pulls full-size originals over the wire.
Authoring workflow & approval
Largely intact — the biggest reassurance point for content teams evaluating the move. What changes is preview: what an author sees in the fragment editor is no longer what a customer sees in the app, so a new "how does this look live" step has to exist in the workflow, not get skipped.
i18n & localization
Multi Site Manager language copies map to content-fragment locale variants, but the translation connector that watched page trees now has to watch fragment models instead. It is a remap of what triggers a translation job, not a lift-and-shift of the existing configuration.
Personalization & targeting
ContextHub-based page personalization does not carry over automatically. Targeting rules move to the edge or the app layer, calling Adobe Target's delivery API directly against the fragment content rather than the rendered page — the rule logic often survives the move, the trigger mechanism rarely does.
Authoring doesn't change. What changes is the assumption that what an author sees in the fragment editor is what a customer sees in the app — headless breaks that assumption on day one.
SEO & rendering strategy
The SEO risk is a rendering problem, not a URL problem.
A headless AEM setup has no page URLs to preserve by default — routing ownership moves to the consuming app. The redirect-mapping problem that dominates a platform migration mostly doesn't apply here.
What replaces it is a rendering problem. Content fragments delivered through the API are structured data, not rendered HTML, so the app has to server-render or statically generate any page that needs to rank.
Structured data ownership moves too — product, article, and breadcrumb schema now live in the frontend's template code, not an AEM component, so schema coverage has to be re-audited page type by page type.
Canonical handling gets more involved with two consumer surfaces: a web canonical for the storefront, and no canonical concern at all for the native app, which search engines never crawl directly.
Crawl monitoring shifts too — instead of watching for broken redirects, the signal to watch is render coverage: how many pages Search Console reports as successfully rendered versus fetched, since a fetch success with a rendering failure is the headless-specific version of a 404.
A content fragment delivered by API is data, not a page. If the storefront renders it client-side only, Google reads an empty shell — the migration succeeds and the SEO regresses anyway.
Integration parity
What AEM did invisibly — and where it goes now.
AEM Sites ran each of these implicitly, tied to the rendered page. Headless needs each one re-homed as its own explicit system.
Dispatcher caching
Page-level caching in front of the AEM publish tier, invalidated on page activation.
A CDN or edge cache in front of the headless API, keyed on fragment and locale rather than rendered page URL, invalidated on publish events.
Adobe Target personalization
Page-level experience fragments swapped in and out by ContextHub at render time.
The app or edge layer calls Target's delivery API directly, merging the decision into the API response before the client ever renders anything.
Sling / Oak search indexing
Content indexed implicitly as pages are activated, riding on the repository's own index.
A dedicated search index (Algolia, Elastic) fed by content-fragment publish events, built and owned as an explicit pipeline rather than inherited.
Translation connectors
Watch page trees, submit page-level translation jobs to the TMS on a schedule.
Remapped to submit and receive jobs at the fragment level, matching the new content model instead of the retired page hierarchy.
Tag management & analytics
Injected via AEM client libraries baked into the rendered page's HTML output.
Owned by the consuming frontend's own tag layer — the app fires its own events against fragment data, on its own release cycle.
Cutover mechanics
One template at a time, one content model, two surfaces.
This runs template by template, not as a single switch. Each template gets a dual-publish period — fragment and page both live — before the classic path retires.
Where our embedded team ran this pattern
For an enterprise luxury fashion retailer, our embedded engineers rebuilt the content delivery layer so AEM content published via a headless API to both the Salesforce Commerce Cloud storefront and native mobile — same source, two channels, no vendor handoff.
What actually breaks
Six failure modes we've seen in production.
Client-side-only rendering tanks SEO
A content fragment delivered by API is data, not a page. If the storefront renders it client-side only, crawlers read an empty shell — the AEM migration succeeds on every internal metric and the SEO regresses anyway, usually discovered a month later in a rankings report.
Authors format rich text the new renderer doesn't expect
Rich-text output from the fragment editor carries assumptions the page renderer used to absorb silently — inline styles, nested tables, pasted-from-Word markup. Without a shared sanitization layer, the same fragment can render correctly on web and break on native mobile.
DAM renditions bloat without a CDN in front
Calling the Assets HTTP API directly, without a dynamic-media or CDN layer, means every channel fetches full-resolution originals instead of a sized rendition. Page weight and load time regress exactly where the migration was supposed to improve them.
Authors lose the 'how does this look live' check
Fragment editors show structured data, not a rendered page. Content ships that reads correctly in the editor and wrong in the app — a truncated headline, a broken image crop — because nobody had a live preview step positioned to catch it before publish.
Personalization rules go silent
ContextHub-based targeting rules do not fire against headless delivery by default. A seasonal campaign underperforms for weeks before anyone traces it back to a personalization rule that stopped triggering the moment the template went headless.
Language copies drift out of sync
Multi Site Manager's page-level sync doesn't map cleanly onto fragment structure. Translated fragments quietly fall behind the source language version after a content update, and nobody notices until a customer in a secondary market reports mismatched content.
Rendering model
Traditional AEM Sites vs AEM headless.
| Criterion | AEM Sites (page-based) | AEM headless (fragments + API) |
|---|---|---|
| Authoring experience | In-context WYSIWYG page editing | Structured fragment editing, live preview separate |
| Where rendering happens | AEM publish tier + dispatcher | The consuming app — storefront or native client |
| Channels reached | The web pages AEM renders | Any channel that can call the API — web, native, kiosk |
| Personalization | Native, via ContextHub experience fragments | Rebuilt at the edge or app layer against Target's API |
| SEO risk | Low — AEM renders full HTML by default | Real — the app must server-render to stay crawlable |
| Performance ownership | The dispatcher's caching layer | The consuming app's own CDN and render strategy |
| Engineering investment | Lower — the platform renders the page | Higher — each channel builds and owns its own renderer |
| Best fit | Single web surface, strong existing SEO | Multi-channel content: storefront, native app, or both |
Most enterprises land somewhere between the two rows, not at either end: AEM Sites keeps serving the templates that don't need to reach a second channel, while the templates that do move to the content model on their own schedule.
Questions
AEM to headless, the mechanics answered
- Do we lose AEM's in-context WYSIWYG authoring going headless?
- Authoring itself stays largely the same — the fragment editor still resembles the page editor. What's lost is the direct visual link between what an author edits and what a customer sees, since that now depends on how the consuming app renders the fragment.
- How does SEO work if content is delivered through an API instead of a page?
- The consuming app has to server-render or statically generate the pages that need to rank — content fragments alone are not crawlable. This shifts SEO risk from a URL-mapping problem to a rendering-architecture problem.
- What happens to Adobe Target personalization rules built for AEM Sites?
- Page-level ContextHub rules do not carry over automatically. They get rebuilt to call Target's delivery API directly from the edge or app layer, evaluated against fragment content instead of a rendered page.
- Can we go headless for one channel while AEM Sites keeps serving another?
- Yes — this is the common pattern. AEM Sites keeps serving a web surface that doesn't need multi-channel reach while a native app or a separate storefront consumes the same content through the headless API.
- Do we need GraphQL, or can the Assets and Content Fragment HTTP APIs cover it?
- GraphQL is the better fit when consuming apps need to query specific fields across many fragments efficiently. The REST-based Content Fragment and Assets HTTP APIs work for simpler, per-fragment lookups without a query layer.
- What's the rollback if a headless template underperforms after launch?
- Keep the classic AEM Sites rendering path live behind a per-template flag until the headless surface proves parity against real production traffic — the same phased-cutover discipline as a commerce platform migration.
References
Original sources for the claims above.
- Adobe Experience League — Headful and Headless in AEM — The concept-level reference for running both rendering models in one AEM project.
- Adobe Experience League — GraphQL API for Content Fragments — The query surface consuming apps use to pull structured content by model.
- Adobe Experience League — Assets HTTP API — The REST surface for DAM assets and renditions consumed outside the page renderer.
- Google Search Central — JavaScript SEO basics — How crawling and rendering interact when content is delivered client-side — the core SEO risk in any headless migration.
How an engagement starts
Three steps to a partnership
Intake call
30 minutes. We listen, you talk. No deck.
Diagnostic
We audit the surface, name the bottleneck, propose a path.
Kickoff
Senior engineer in your standup by week two.
Ready to decouple AEM?
Tell us which channels need to share content and which templates carry the most SEO weight. We'll come back with the content model and the rollout order.