# EDS blocks, loading phases and telemetry

> **Verified:** 2026-09 against https://www.aem.live/developer/block-collection, https://www.aem.live/developer/keeping-it-100 and https://www.aem.live/developer/rum

Open this for the anatomy of a block, the three loading phases, the RUM and experimentation hooks, or how to test a block.

## A block

```
blocks/cards/cards.js    → export default function decorate(block) { … }
blocks/cards/cards.css   → every selector scoped under .cards
blocks/cards/_cards.json → the Universal Editor model, on xwalk projects only
```

```js
import { createOptimizedPicture } from '../../scripts/aem.js';

export default function decorate(block) {
  const ul = document.createElement('ul');
  [...block.children].forEach((row) => {
    const li = document.createElement('li');
    li.append(...row.children);
    [...li.children].forEach((col) => {
      col.className = col.querySelector('picture') ? 'cards-card-image' : 'cards-card-body';
    });
    ul.append(li);
  });
  ul.querySelectorAll('picture > img').forEach((img) => img.closest('picture')
    .replaceWith(createOptimizedPicture(img.src, img.alt, false, [{ width: '750' }])));
  block.replaceChildren(ul);
}
```

Rules that keep a block maintainable:

- **Decorate the DOM the author produced.** A block that discards `block.children` and rebuilds from hard-coded strings is a template, and the author has no control over it any more.
- One block, one purpose, a few hundred lines at most. Variants come from classes in the block name (`Cards (compact)` → `class="cards compact"`), not from new blocks.
- Use the helpers in `scripts/aem.js` — `createOptimizedPicture`, `loadCSS`, `loadScript`, `getMetadata`, `readBlockConfig`, `toClassName`, `decorateIcons`. **Never edit `scripts/aem.js`**: it is the shared library that tracks upstream, and a local edit means every future boilerplate update is a merge conflict. Project logic goes in `scripts/scripts.js`.
- CSS is mobile-first, scoped to the block class, and uses the custom properties defined in `styles/styles.css`. No global resets inside a block.
- `decorate` may be `async`, but only `await` what must resolve before the block is visible.

## The three phases

| Phase | Where | What belongs there |
|---|---|---|
| **Eager** (`loadEager`) | `scripts/scripts.js` | Decorate the page, load the first section only. The LCP element renders here. Nothing third-party, no second origin |
| **Lazy** (`loadLazy`) | `scripts/scripts.js` | Remaining sections and blocks, header and footer fragments, `lazy-styles.css`, fonts |
| **Delayed** (`scripts/delayed.js`) | loaded from `loadDelayed` | Analytics, tag managers, chat, consent, marketing pixels — everything third-party |

The rule for the delayed phase is that it **should not start until at least three seconds after the LCP event**. The boilerplate no longer hard-codes that timer, so a project that copies the boilerplate and adds a tag manager to `delayed.js` without setting the delay is loading it immediately. Check your `loadDelayed` implementation rather than assuming.

The other LCP rule that gets broken: **no second origin before LCP**. A font, a script or an image from another host in the eager phase costs a DNS lookup, a TLS handshake and a connection, and no amount of later optimisation buys it back. The boilerplate aims to keep the pre-LCP payload around 100 KB.

**Auto-blocking** (`buildAutoBlocks` in `scripts.js`) turns content patterns into blocks — a leading picture plus an H1 into a hero, a link to `/fragments/…` into a fragment block — so authors do not have to. Keep it deterministic and cheap; it runs in the eager phase on every page.

## Telemetry and experimentation

- **Operational Telemetry / RUM**: the boilerplate samples real user data through `sampleRUM`, which is how you get field Core Web Vitals for the site rather than a lab score. Instrument custom interactions with `sampleRUM('cwv', …)`-style checkpoints rather than adding a second analytics library.
- The **experimentation plugin** runs A/B tests and audience-based variants at the edge, driven by page metadata. It is the supported way to personalise an EDS page; a client-side personalisation library loaded early is the way to lose the performance score.

## Testing a block

The boilerplate ships a test setup based on `@web/test-runner` running real browsers against the real DOM — which suits blocks, because a block *is* a DOM transformation:

```js
import { readFile } from '@web/test-runner-commands';
import { expect } from '@esm-bundle/chai';

document.body.innerHTML = await readFile({ path: './cards.fixture.html' });
const decorate = (await import('../../blocks/cards/cards.js')).default;

describe('cards block', () => {
  it('turns rows into list items', async () => {
    const block = document.querySelector('.cards');
    await decorate(block);
    expect(block.querySelectorAll('li').length).to.equal(3);
  });
});
```

Write the fixture as the HTML the document authoring pipeline actually produces (a `div` per row, a `div` per cell), not as hand-idealised markup — the whole value of the test is catching the difference.

Lint (`npm run lint`: ESLint airbnb-base plus Stylelint) is part of the same gate. There is no build step and no transpile: the ES modules you write are the ES modules that ship.
