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.yamlpoints at the AEM author service instead of a document store.paths.jsonmaps AEM author paths to the site's URL structure (so/content/acme/en/homeserves 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-levelcomponent-models.json,component-definition.jsonandcomponent-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.pageis preview;https://main--<repo>--<owner>.aem.liveis 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
.livethrough 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. .hlxignorekeeps 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.