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.childrenand 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 editscripts/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 inscripts/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. decoratemay beasync, but onlyawaitwhat 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 withsampleRUM('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.