Skip to main content

Best practices

This chapter is the running list of "things you wish someone had told you" - patterns that pay off, mistakes that bite teams more than once, plus licensing notes and upstream resources.

Hybrid routing​

EDS and traditional AEM Publish coexist well. Common pattern:

www.example.com/           - EDS (marketing homepage)
www.example.com/blog/      - EDS (blog)
www.example.com/products/  - EDS (catalog)
www.example.com/account/   - AEM Publish (authenticated)
www.example.com/api/       - AEM Publish (servlets)
www.example.com/forms/     - EDS for Forms

Configure path-based routing at your CDN (Adobe-managed CDN, or a BYO CDN in front). Two practical rules:

  1. One origin per path prefix. Routing rules should be flat - not deeply nested regex. The simplest one wins.
  2. Cache identity stays consistent. A URL that flips between origins under different conditions is a bug magnet - cache key, surrogate keys, and purge windows have to align.

Shared content​

Content Fragments authored in AEM are consumable from both sides:

  • Traditional AEM: via Sling Models or the GraphQL endpoint
  • EDS: via the Content Fragment / GraphQL API or Universal Editor

Keep one source of truth. A "product description" lives once; both AEM Publish and EDS pull it.

Migration strategy​

Most teams migrate incrementally:

  1. Start with EDS for new marketing pages or a redesign
  2. Keep existing AEM Sites for pages with complex server-side logic
  3. Gradually move pages to EDS as their blocks mature
  4. Retire Publish + Dispatcher for fully migrated sites (often optional -- the two-origin setup can stay indefinitely)

Common pitfalls​

PitfallWhy it happensFix
Lighthouse score drops below 100Render-blocking third-party script in <head>Move it to delayed.js
Block JS runs before DOM is readyMisconception - decorate() is called after DOM insertionTrust the runtime; remove DOMContentLoaded workarounds
Content changes not on productionAuthor clicked Preview but not PublishTrain authors on the two-step flow; add a Sidekick plugin that highlights "preview-only" rows
Custom domain shows stale contentBYO CDN missing push invalidationConfigure push invalidation - see Customizing
Authors see broken layout in Word/DocsAuthoring table structure doesn't match block expectationsDocument the content model per block; ship a Sidekick block library so authors copy from a working example
Block CSS leaks to other blocksGlobal selectors in block.cssScope every selector under .blockname; lint for it in CI
Large scripts.js bundleFunctionality bundled instead of splitEach block owns its JS / CSS; lazy-load shared utilities from /plugins/
EDS and AEM Publish disagree on the same URLTwo origins claim the same pathUse path-based routing at the CDN - no overlapping prefixes
data-aue-* attributes lost during decorationBlock decorate() clones nodes instead of moving themRe-parent (block.append(child)) instead of cloneNode
Slow PDP / PLP under loadDecoration fetches data in series across blocksHoist the data fetch to scripts.js and pass results to blocks
Deleted page is still liveDeleting the source document does not unpublish itUnpublish (Sidekick or Admin API) before deleting; run an Admin API drift audit
API key leaked to the browserKey embedded in a blockMove secrets server-side; have a thin proxy that adds the Authorization header

Performance hygiene​

  • Check performance on every PR (see Measuring on every PR).
  • Budget delayed scripts. Even delayed.js can hurt if it pulls 200KB.
  • Profile blocks in DevTools' Performance tab when adding interactivity. The decoration step shows up as user timing if you performance.mark it.

Authoring hygiene​

  • Block library in Sidekick is your contract with authors. Keep it current.
  • Section metadata is the right home for theming hints. Don't reinvent.
  • Fragments (the fragment block) keep shared copy DRY - footers, banners, CTAs.

Operations hygiene​

  • Schedule a weekly drift audit (Admin API) that flags pages where source is newer than live.
  • Use snapshots before high-stakes publishes (campaign launches, price changes).
  • Watch the /log endpoint for unexpected publishers - it's the audit trail.

Licensing​

AspectDetails
Included withAEM Sites as a Cloud Service
Page viewsCovered under the AEM Sites page-view tier
CDN trafficAdobe-managed CDN included; BYO CDN is the customer's responsibility
AuthoringAEM authoring or document-based (SharePoint / Google Drive included)
FormsEDS for Forms may require a separate AEM Forms entitlement
CommerceCommerce Storefront requires Adobe Commerce or a third-party backend
Universal EditorIncluded with AEM as a Cloud Service
SidekickFree Chrome / Edge extension
Admin APIIncluded; rate-limited per repo

External Resources​

See also​