aem-eds-kit / AEM to EDS migration

Migration guide

AEM to EDS Migration Guide

Moving from classic Adobe Experience Manager (AEM Sites) to Edge Delivery Services is really two jobs: migrating components (dialogs, HTL, CSS) and migrating content (authored pages). aem-eds-kit automates the component side deterministically and scaffolds the rest - so you don't rebuild everything by hand, or burn tokens doing it.

●Deterministic dialog → UE model ●17 field types mapped ●Zero tokens for the schema

Two migrations, not one

Components and content move differently - and from different best sources. Keep them on separate tracks:

◧ Components

The authoring schema, markup and styles behind each component.

  • Dialog → repo XML (_cq_dialog/.content.xml) — deterministic
  • CSS → clientlib on disk / rendered page — scoped into the block
  • HTML / JS → HTL + rendered DOM — ported to decorate()

Content

The authored pages your editors actually maintain.

  • Source → rendered HTML of live pages (not JCR XML)
  • Map → page sections become EDS blocks
  • Land it → author in DA / Docs / SharePoint or Universal Editor

Why dialogs map cleanly

A classic AEM component stores its authoring schema in a Touch UI dialog. Granite/Coral has a finite set of sling:resourceType field types, so mapping them onto the 17 Universal Editor field types is a deterministic table - not guesswork:

Granite / Coral dialogUniversal Editor field
form/textfield→text
form/textarea · RTE→textarea · richtext
form/select (items)→select (+ options)
form/checkbox→boolean
form/numberfield→number
form/datepicker→date-time
form/pathfield · pathbrowser→aem-content
fileupload · image→reference
form/multifield→container (repeatable)
tags · tagpicker→aem-tag
tabs · fieldset→tab / grouping

What eds migrate component does

One deterministic pass turns a component's dialog into a working block - no agent, no tokens:

Source _cq_dialog/
.content.xml
+ clientlib
→
eds migrate component parse dialog
map 17 fields
pull & scope CSS
→
Output blocks/hero/
hero.js · hero.css
_hero.json

Migrate a component, step by step

  1. Install the CLI 
    $ npm i -g aem-eds-kit
  2. Set up the EDS project Pick your authoring model - interactive when you omit the flags. 
    $ eds init
  3. Migrate the dialog → block + UE model Parses the dialog, maps the 17 field types, writes blocks/hero/ (hero.js, hero.css, _hero.json) and pulls the clientlib CSS in automatically. 
    $ eds migrate component ./ui.apps/.../components/hero
  4. Port behaviour & CSS Move the HTL logic into decorate() and review the scoped CSS.
  5. Enrich (optional) Model fields, structured data, analytics. 
    $ eds model add hero teaser
$ eds schema block hero --type Article
$ eds track block hero
  6. Preview Width-honest, at the design's own breakpoints (falls back to 375 / 768 / 1280). 
    $ eds block preview hero

Getting the CSS right

✦

The authored clientlib CSS (often LESS) is a starting point. The most faithful CSS comes from the rendered page, because it resolves variables and the cascade. Bring the component's real styles into the block CSS and scope them under .hero.

Migrating content

Authored pages are best migrated from their rendered HTML, not from JCR XML or Sling Model JSON (which carry data, not the full visual structure). Scrape the live page, map its sections to EDS blocks, and author the result in your content source - where it lands depends on the model:

▤ Document Authoring

Google Drive, SharePoint or DA (da.live).

  • Starter documents / initial content
  • eds template new generates a page
  • For DA it pushes straight to da.live

◆ Universal Editor

Crosswalk - author in-context in AEM.

  • Repo holds the component library
  • component-definition / -models / -filters
  • eds template new writes the initial content
✦

Still deciding? eds init is interactive - it walks you through Universal Editor, DA, Google Drive and SharePoint, then wires the repo for whichever you pick. For a deeper comparison, read Document Authoring vs Universal Editor.

FAQ

Is AEM to EDS migration automatic?

The deterministic parts - dialog → Universal Editor model mapping and clientlib CSS extraction - run with no agent and no tokens. HTL → vanilla JS and final styling are agent-assisted or manual, because they involve behaviour, not just a schema.

Do I need to rewrite every component?

No. eds migrate component generates the block skeleton + authoring model for each component from its dialog, so you start from a working structure instead of a blank file.

Does EDS use templates like AEM /conf?

Not a single /conf. For document models, templates are starter documents (initial content); for Universal Editor, they're AEM editable templates plus the component library. eds template new generates the initial content either way.

Document Authoring vs Universal Editor →   Command reference →