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

> **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 |

```yaml
# 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

```bash
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.
