Critical CSS Rules
Critical CSS (also called "above-the-fold CSS") is the minimal set of styles a browser needs to render the visible part of a page on first paint. Inlining it into the <head> lets the page start rendering immediately, while the full stylesheets load asynchronously in the background. This is one of the most effective ways to improve Largest Contentful Paint (LCP) and First Contentful Paint (FCP).
The extension lets you define different critical CSS per page type — not only the standard Magento page types (home, CMS, category, product), but any page served by a third-party module — matched by full action name, layout handle, or a URL regular expression.
Where to manage rules
Open PageSpeed Optimizer → Critical CSS Rules in the Magento admin. The grid lists every rule with its ID, Name, Match type, Match value, Store view, Priority, Active flag, and Created / Updated timestamps.
From the grid you can Add New Rule, Edit a rule from the Actions column, or use the mass-action dropdown to Delete, Enable, or Disable several selected rules at once.
If only the Optimizer module is installed, the Critical CSS Rules entry is also available under the Magento Content menu, so the grid stays reachable even when the shared "Mirasvit" menu is not shown.
Creating a rule
Click Add New Rule and fill in the form.
General
- Name: a human-readable label for the rule (e.g.
Product page critical CSS). - Active: when set to No, the rule is ignored on the storefront.
- Priority: when more than one rule matches the same page, the rule with the highest priority wins. Ties are broken by the lowest rule ID (the rule created first). Use this to let a specific rule override a more general one.
- Store view: limit the rule to a single store view, or choose All store views to apply it everywhere.
Match type and Match value
The Match type determines how the rule is paired with a page, and Match value holds the value to compare against:
| Match type | Match value example | How it is matched |
|---|---|---|
| Full action name | catalog_product_view | Exact match against the page's full action name ({route}_{controller}_{action}). |
| Layout handle | cms_index_index | Exact match against one of the page's layout handles: default, {route}_{controller}, or the full action name. |
| URL pattern | product/view or #^/sale/# | A regular expression matched against the request URI. |
In developer mode you can append ?debug=template to a URL, or look at the <body> CSS classes — Magento adds the action name as a class (for example catalog-product-view, which corresponds to catalog_product_view).
If your pattern does not already start with a regex delimiter (/, #, ~, !, @, or %), the extension wraps it in #…# automatically (so product/view becomes #product/view#). Provide your own delimiters when you need flags or anchors, e.g. #^/sale/#i. Invalid patterns are skipped and logged as a warning, so a single broken rule can never break the page.
Critical CSS
- Critical CSS: the CSS to inline into the
<head>of every matching page. You can paste it manually or generate it automatically with the built-in extractor (see below).
When a rule matches, the extension injects the CSS as <style data-mst-critical-css="1">…</style> at the start of the <head> — before the page's own stylesheets, so those stay authoritative and the page renders correctly whether or not the remaining CSS is deferred. Rules are not applied to AJAX requests.
Generating critical CSS automatically
Each rule form includes an Extract critical CSS automatically section with a URL to render, Viewport(s), Timeout, and an optional Wait for selector field. Clicking Extract Critical CSS renders the page in a headless Chromium browser, collects the CSS actually used above the fold, and fills the Critical CSS field for you.
The same extraction is available from the command line — useful for build pipelines and bulk updates:
bin/magento mst:optimize:critical-css:extract --url=https://example.com/catalog/category/view/id/5 --save-to-rule=42
See Command line interface for the full option list and prerequisites.
The extractor ships pre-built inside the module — there is no npm install and no browser download. To run it (admin button or CLI) the host needs Node.js ≥ 18 and a system Google Chrome / Chromium binary; set the CHROME_PATH environment variable if Chrome is installed in a non-standard location. It launches a real browser and makes HTTP requests to the URL you supply, so run it from a machine you control and only point it at URLs you own and trust.
Magento Cloud web nodes have no Node.js or Chrome, so the Extract button and the CLI cannot run there. The runtime (inlining critical CSS and deferring the rest) is pure PHP and works on Cloud normally — you only need to generate the CSS elsewhere. See Using critical CSS on Magento Cloud below.
Deferring the remaining (non-critical) CSS
Inlining critical CSS gives the biggest win when the rest of the stylesheets no longer block rendering. Enable Stores → Configuration → Mirasvit Extensions → Google Page Speed Optimizer → CSS optimization → Defer Non-Critical CSS when Critical CSS Rule matches.
When that option is enabled and a Critical CSS Rule matches the current page, every remaining stylesheet in <head> is converted to an async preload+swap so it does not block the first paint. Stylesheets covered by the Add styles to HTML from CSS resources (inline) list or the dedicated Do not defer CSS that contains list are left untouched.
Deferral has its own Do not defer CSS that contains field (one file name or fragment per line), separate from the move-to-bottom Do not move CSS that contains list — so excluding a stylesheet from one does not affect the other.
This toggle only takes effect on pages where a Critical CSS Rule actually matches, so you can roll the feature out page type by page type.
Recommended workflow
- Create a rule for the page type you want to optimize (e.g. product pages → match type Full action name, value
catalog_product_view). - Use Extract critical CSS automatically (or the CLI) against a representative URL of that page type to populate the Critical CSS field.
- Save the rule and verify it on the storefront — view the page source and look for
<style data-mst-critical-css="1">in the<head>. - Once the inlined CSS renders the page correctly, enable Defer Non-Critical CSS when Critical CSS Rule matches to stop the full stylesheets from blocking the first paint.
- Measure with Lighthouse / PageSpeed Insights and adjust the extracted CSS or viewports if needed.
Using critical CSS on Magento Cloud
The feature has two parts, and they behave differently on Magento Cloud:
- Serving the critical CSS (runtime) — inlining the stored CSS into
<head>and deferring the rest — is pure PHP and works on Magento Cloud exactly as on any other host. Nothing special is required. - Generating the critical CSS (the extractor) — the admin Extract button and the
mst:optimize:critical-css:extractCLI — needs Node.js and a Chrome/Chromium browser. Magento Cloud web nodes provide neither, and their filesystem is read-only, so the extractor cannot run on Cloud.
The solution is to generate the CSS off-Cloud and store it in the rule. Because rules live in the database, the Cloud storefront then serves the stored CSS at runtime like any other rule.
Recommended workflow for Cloud
-
Generate the CSS where Node.js + Chrome are available — your local machine, or a CI runner. Point the extractor at the page you want to optimize:
bin/magento mst:optimize:critical-css:extract \
--url=https://example.com/catalog/category/view/id/5 \
--output=/tmp/category.css -
Store the result in a rule on the Cloud store, by either:
- pasting the generated CSS into the Critical CSS field of a rule in the Cloud admin and saving; or
- running the extractor with
--save-to-rule=<id>from a machine that can reach the Cloud database (for example over an SSH tunnel), so it writes the CSS into the rule directly.
-
Verify on the storefront — view the page source and look for
<style data-mst-critical-css="1">in the<head>. -
Once it renders correctly, enable Defer Non-Critical CSS when Critical CSS Rule matches as usual.
Keeping critical CSS up to date
The stored critical CSS is a snapshot taken when you ran the extractor. If you later change the theme, add styles, or add a new above-the-fold block, the snapshot becomes stale — re-run Extract (or the CLI) on the affected rule to refresh it. This matters most with deferral on, where missing styles only arrive once the deferred stylesheets load.
To automate this, enable Stores → Configuration → … → CSS optimization → Scheduled Critical CSS Re-extraction:
- Scheduled Critical CSS Re-extraction: turns the cron job on (off by default).
- Re-extraction Frequency: Daily, Weekly, or Monthly.
- Re-extraction Start Time: the time of day the job runs.
When enabled, a cron job re-runs the extractor for every active rule that has a stored URL to render, and updates its Critical CSS automatically.
Like the manual extractor, the scheduled job runs the local extractor, so the cron host needs Node.js and a system Chrome. It therefore does not run on Magento Cloud web nodes — on Cloud, keep regenerating off-Cloud (local/CI) as described above.
Troubleshooting
The critical CSS is not appearing on the page
- Confirm the rule is Active and its Store view includes the store you are testing.
- Verify the Match type / Match value actually matches the page (for Full action name, compare against the page's body class; for URL pattern, test your regex against the request URI).
- The processor skips AJAX requests and any response without a
</head>tag. - Flush the Magento cache after creating or editing a rule.
The wrong rule is being applied
Multiple rules can match the same page. The rule with the highest Priority wins; if priorities are equal, the rule with the lowest ID wins. Raise the priority of the rule you want to take precedence.
The page looks broken / unstyled above the fold
The extracted critical CSS is incomplete for that page type. Re-extract with a viewport that matches your audience (add a mobile viewport such as 375x812), or use the Wait for selector option so coverage is collected only after the key content has rendered.
Styles flash or shift after load (with deferring enabled)
This usually means some above-the-fold styles are missing from the critical CSS, so they only arrive when the deferred stylesheets load. Re-extract the critical CSS, or add the affected stylesheet to the Add styles to HTML from CSS resources list so it is not deferred.