Org Skills

EDS blocks, loading phases and telemetry

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/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
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:

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.