The theme engine streams server-rendered HTML and then hydrates it in the browser. Most storefront performance problems come from a disagreement between those two steps, not from the size of a download.
This section gives the rules that keep a theme fast. The rules apply to every section, including a section type that no existing theme has shipped.
The three problems, in priority order
1. Layout shift (CLS)
Content that appears or changes size after the first paint pushes the rest of the page down. This is the largest and the most repairable problem.
Cause: an element with no reserved height, or content that the client fetches after the first paint.
Fix: reserve the final height in the server HTML, and never let that height collapse. Read Section Performance Rules, Rule 2 and Rule 3. A web font with different metrics also causes a reflow, which Rule 9 removes.
2. Main-thread blocking (TBT)
The browser must parse and run every byte of the synchronous bundle before the page responds to a tap. Time spent here is time the shopper waits.
Cause: barrel imports, heavy libraries in the synchronous bundle, inline SVG modules, and JavaScript timers that set state.
Fix: run less JavaScript before hydration. Read Rules 5 to 8.
3. Hero paint (LCP)
The largest element usually downloads quickly. The delay comes from the element moving after it paints, which makes the browser measure the paint again.
Cause: a hydration mismatch that changes the markup, or a media box that re-sizes when the real image arrives.
Fix: keep the server HTML equal to the first client render. Read Rule 1.
How to measure
- Run Lighthouse on mobile, with throttle applied.
- Measure the plain storefront URL. A cache-skip query parameter changes the result.
- Read TBT and CLS. Do not read the overall score. On a shared cluster the score moves with network noise, and TBT and CLS do not.
- Run the same page more than one time. A layout shift that appears in some runs and not in others is a real defect, not noise. It means the shift depends on when an API responds.
Two kinds of work
The pages in this section cover two kinds of change, and you can adopt them separately.
Theme-side rules work with plain React and CSS. They need nothing from the engine, and they apply to every release. Read Section Performance Rules.
Engine declarations opt the theme into deferred hydration, reserved section heights, and route prefetch. The theme declares them on the theme bundle root, and the engine acts on them. Read Deferred Hydration and Lazy Sections.
The theme-side rules come first. Deferred hydration reduces the work the browser does, but it introduces a placeholder for every deferred section. A section that has no reserved height, or whose skeleton does not match its content, shifts the page harder once it is deferred than it did before.
Version note
The engine declarations are not present in every release, and a higher version number does not always contain them. Confirm them against the platform release that your sales channel runs before you depend on them.
Read next
| Page | Use it when |
|---|---|
| Section Performance Rules | You write any section or component |
| Deferred Hydration and Lazy Sections | You opt the theme into lazy sections |
| Performance Checklists | Before you ship a theme or a section |