Layout Cache: Warm Up the Layout Cache at Deploy Time¶
User Guide¶
CopeX GmbH
Web: https://copex.io
Email: office@copex.io
Inhaltsverzeichnis / Table of Contents¶
| Abschnitt / Section | Seite |
|---|---|
| 1 Was es macht / What it does | 3 |
| 2 Wann sinnvoll / When to use | 3 |
| 3 Voraussetzungen / Requirements | 4 |
| 4 Installation | 4 |
| 5 Aktivierung / Activation | 5 |
| 6 Verwendung / Usage | 5 |
| 7 Was tun bei Problemen / Troubleshooting | 7 |
| 8 Für Entwickler / For Developers | 8 |
1 What it does¶
When Magento renders a page for the first time after a deployment or cache:clean, it merges multiple layout XML files from core, theme, and modules. This merge step takes 200–500 ms per unique page type — the first visitors after a deploy experience this delay.
Layout Cache eliminates this first-request spike by warming the layout merge cache during deployment. Eight high-value page types (homepage, category, product detail, cart, checkout, customer account) are pre-computed for each store view and stored in the layout cache.
Real user requests after deployment load the layout cache from Redis — the merge step is skipped entirely.
2 When to use¶
- First page loads after deployments are noticeably slower than subsequent ones
- Monitoring shows response time spikes after cache invalidations
- Shop has multiple store views — each benefits separately
3 Requirements¶
- Magento 2.4.7 to 2.4.9
- PHP 8.3 to 8.5
copex/module-performance-suite(providesBuilderPool)copex/module-core>1.1.0
4 Installation¶
composer require copex/module-layout-precompile
bin/magento module:enable CopeX_LayoutPrecompile
bin/magento setup:upgrade
Alternatively, install the complete suite:
composer require copex/performance-suite-bundle
5 Activation¶
Layout Cache has no env.php flag. The layout builder is active as soon as the module is
enabled — LayoutBuilder::isEnabled() returns a constant true and does not consult
copex/performance/preloaders/enabled. To populate the snapshots, run:
bin/magento copex:performance:build
6 Usage¶
bin/magento copex:performance:build¶
Runs all registered builders — layout pre-warming is included automatically:
bin/magento copex:performance:build
With -v for detailed per-handle and per-store-view output:
bin/magento copex:performance:build -v
Recommended deployment sequence:
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento copex:performance:build
bin/magento cache:flush
Important: copex:performance:build must run before cache:flush — otherwise the pre-warmed entries are discarded immediately.
Warmed per store view: homepage, category listing, product detail (simple, configurable, bundle), shopping cart, checkout, customer account.
7 Troubleshooting¶
Kill switch:
bin/magento module:disable CopeX_LayoutPrecompile
bin/magento setup:upgrade
The layout builder is removed from the BuilderPool. All other Performance Suite features remain active.
Layout cache is not being warmed: check the module status. Run bin/magento copex:performance:build -v for detailed output. Check var/log/system.log for layout errors.
A handle set fails: failures are printed inline but do not stop the entire build. Fix the root cause in the layout XML, re-run setup:di:compile, then rebuild.
8 For Developers¶
The module registers itself in the CopeX_PerformanceSuite BuilderPool at priority 20 (after config compilation, before DI warmers). Custom builders can be registered following the same pattern via di.xml — implement BuilderInterface from copex/module-performance-suite.
CopeX GmbH — Web: https://copex.io — Email: office@copex.io