Going Headless with AEM: When Content Fragments + GraphQL Actually Make Sense (and When They Don't)
1. Content Fragments aren't a drop-in replacement for page components
Content Fragments (CFs) model structured content well product data, article bodies, reusable content blocks but they're not meant to replace your entire page authoring model. Teams that try to force every page into pure CF + GraphQL often end up rebuilding layout/personalization logic that AEM Sites already gave them for free. Headless works best for content that's genuinely reused across channels (app, web, kiosk, partner feed), not for one-off marketing pages that only ever render in AEM Sites.
2. GraphQL persisted queries are not optional in production
If you're calling the GraphQL endpoint with ad-hoc queries from the front end, stop Cloud Service requires persisted queries for production use (arbitrary GraphQL queries against Publish are disabled by default for security/performance reasons). Every query needs to be registered as a persisted query via a content package or the endpoint. Teams that build their POC with ad-hoc queries and only discover this at launch time lose real days re-architecting the front-end data layer.
3. Content Fragment Models are schema decisions treat them like one
Once front-end apps are built against a Content Fragment Model's structure, changing field names or types becomes a breaking-change exercise across every consuming channel, not just a CMS content update. Version your Content Fragment Models deliberately (additive changes only where possible) the same way you'd version a public API because that's effectively what it is.
4. Preview and publish flows get more complex, not less
With traditional AEM Sites, authors preview a page and it looks like the final page. In headless setups, the "preview" is often a separate front-end app rendering the CF data, which may or may not reflect draft/unpublished content accurately depending on how your SPA/app is wired up. Budget real UX work for author preview this is one of the most common complaints from content teams after a headless rollout, and it's rarely scoped properly upfront.
5. SPA Editor vs. fully decoupled front end is a real architectural fork
If you want in-context authoring (WYSIWYG-style editing inside AEM) with a React/Angular front end, you need the SPA Editor integration, which has its own constraints (component mapping, editable templates). If you go fully decoupled (a Next.js app pulling from GraphQL with zero AEM UI integration), you lose in-context editing entirely and authors work blind against a schema. Pick this deliberately don't let it get decided implicitly by whichever dev started building the front end first.
6. Don't underestimate the caching strategy rework
Traditional AEM dispatcher caching assumes HTML pages. Headless content served via GraphQL/API needs its own caching layer (CDN-level API caching, cache invalidation tied to CF publish events) that's architecturally separate from your dispatcher rules. This is frequently missed in project estimates because "caching" sounds like a solved problem from the Sites side, but the headless caching model is genuinely different.
Bottom line: headless isn't "better AEM," it's a different tool for a different problem content that needs to reach non-web channels or highly custom front ends. If your use case is "we want a modern-looking website," you probably don't need headless at all; you need a better front-end build on top of traditional AEM Sites.