Org Skills

EDS project setup — content sources, xwalk, sheets and config

Supporting material for aem-edge-delivery-services. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified: 2026-09 against https://www.aem.live/docs/config-service-setup, https://www.aem.live/developer/indexing and https://experienceleague.adobe.com/en/docs/experience-manager-learn/sites/edge-delivery-services/developing/universal-editor/1-new-code-project

Open this when starting a project, choosing a content source, wiring Universal Editor authoring, or looking for the file that holds a site setting.

Content sources

Source Authoring Project setup
Google Drive / SharePoint Word or Google Docs fstab.yaml mountpoint, or the configuration service
Document Authoring (da.live) A browser-based document editor built for EDS Content source configured for DA; no Drive or SharePoint account needed
AEM author (Universal Editor) The Universal Editor against AEM The aem-boilerplate-xwalk template — see below
# fstab.yaml — document-based projects
mountpoints:
  /: https://drive.google.com/drive/folders/<folder-id>

The configuration service is the current mechanism and overrides fstab.yaml and .helix/config.xlsx once it is enabled for a site. It is also what makes "repoless" setups possible: many sites sharing one code repository, each with its own content source and configuration. Check which mechanism your project uses before editing either — a change to fstab.yaml on a config-service site does nothing.

Universal Editor authoring (xwalk)

Start from the adobe-rnd/aem-boilerplate-xwalk template rather than the plain boilerplate. Beyond the usual files:

  • fstab.yaml points at the AEM author service instead of a document store.
  • paths.json maps AEM author paths to the site's URL structure (so /content/acme/en/home serves at /).
  • Each block carries its own Universal Editor model, definition and filter JSON — conventionally blocks/<name>/_<name>.json — which the build merges into the repository-level component-models.json, component-definition.json and component-filters.json. Those three files are what the Universal Editor reads to know which components exist, what fields they have and where they may be placed.
  • Authors work in AEM with the Universal Editor and the Sidekick; preview and publish behave as they do on a document project.

A block without a model JSON simply does not appear in the editor's component list. That is the first thing to check when a new block "does not show up".

URLs and the publishing model

  • https://main--<repo>--<owner>.aem.page is preview; https://main--<repo>--<owner>.aem.live is live. Every branch gets its own preview host, so keep branch names short and lowercase — they become part of a hostname, and long names get rejected.
  • Authors use the Sidekick to preview and publish. Production traffic points at .live through your CDN.
  • The Admin API (admin.hlx.page) drives preview, publish, index and cache operations programmatically — bulk publishing after a content migration, or a CI step that re-indexes. It is also how you script an unpublish.
  • .hlxignore keeps files in the repository out of what is served.

Sheets, indexes and site files

File / path Purpose
/query-index.json The index of page metadata used for listings, search and sitemaps. The index configuration is managed through the configuration service (the Index Admin tool); older projects carry it in the repository
any spreadsheet → /<name>.json Any sheet is served as JSON: { total, offset, limit, data: [...] }, with ?offset=, ?limit= and ?sheet= for multi-sheet workbooks
redirects sheet 301 redirects
head.html Markup injected into every page's <head> — the one place project-wide tags belong, and still not the place for a tag manager
404.html The not-found page
placeholders.json (a sheet) UI strings, so blocks are not littered with English literals
metadata.xlsx Bulk page metadata by path pattern, instead of a Metadata table on every document
helix-sitemap.yaml Sitemap generation configuration

Use a sheet for anything that is content or configuration. Hard-coding a list of offices, a set of labels or a feature flag in a block's JavaScript means an author cannot change it, which defeats the point of the platform.

CDN and invalidation

EDS is served from its own edge. In front of it you can run the Adobe-managed setup or your own CDN (Cloudflare, Akamai, Fastly, CloudFront are the documented options), configured through the configuration service. Publishing pushes invalidation outward, so a published change is live in seconds — if you put a CDN in front without wiring its purge, you have re-introduced the staleness the platform was designed to remove.

Local development and PRs

npm i -g @adobe/aem-cli
aem up                 # http://localhost:3000, local code with content proxied from preview
npm run lint

Push a branch, test on its preview host, and put the before/after URLs in the pull request. The AEM Code Sync bot runs a PageSpeed check on those URLs; a PR that drops the score is not mergeable in spirit, whatever the check status says.

When EDS is the wrong answer

  • Authenticated or entitlement-gated content. EDS serves public, cacheable pages. A login wall belongs on another tier.
  • Forms with server-side logic beyond a submission endpoint — check what the current forms support covers before designing around it.
  • MSM-style rollouts across dozens of markets. Repoless setups plus the configuration service cover "many sites, one codebase" and shared configuration; they do not give you blueprint-to-live-copy inheritance, cancel-inheritance per component, or translation projects. If those words are in the brief, the content source needs to be AEM.
  • App-like, stateful UI. Blocks decorate content. An application embedded in an EDS page is fine; an application as the site is not what the platform optimises for.