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 the webhook target -- 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
Mysterious 404 on a known URLAuthor deleted the doc but didn't unpublishRun 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​

  • Run Lighthouse CI 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.
  • Content fragments (UE only) 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​