CSS
| Toggle | What it does |
|---|---|
| Minify CSS | Strips whitespace and comments from CSS files. Saves roughly 20–30% file size. Almost always safe. |
| Combine CSS | Concatenates multiple CSS files into a smaller number of bundles. Saves on TCP round-trips. |
| Critical Path CSS | Inlines the above-the-fold CSS into the HTML so first paint doesn’t wait for the external file. The rest is loaded asynchronously. |
Don’t combine CSS if your server speaks HTTP/2. HTTP/2 multiplexes many requests over one connection, so combining buys nothing and can hurt cache reuse. Most modern stacks (including ours) are HTTP/2 by default.
Excluded CSS Files
A textarea for files you want to skip from minification or combining. One per line. Useful when a CSS file uses dynamic includes that minification breaks, or a third-party stylesheet must stay separate (e.g., a payment gateway’s iframe styles).Aggressive mobile CSS optimization
A subtoggle that reduces excluded files on mobile. Off by default. Can break visual styling. Enable only if you’re testing carefully on mobile and have a way to roll back.JavaScript
| Toggle | What it does |
|---|---|
| Minify JavaScript | Strips whitespace and comments. ~20% size reduction, almost always safe. |
| Combine JavaScripts | Bundles multiple JS files into fewer requests. Same HTTP/2 caveat as CSS. |
| Load JavaScript deferred | Adds the defer attribute to script tags so they load after the HTML is parsed. |
| Delay JavaScript Execution | Waits to load non-critical JS until the user interacts (scrolls, clicks). Big TTFB win, but breaks JS that needs to run on initial page load. |
Combine vs Defer vs Delay (in plain terms)
- Defer says “browser, run this script after parsing the HTML.” Safe for most scripts. Good default.
- Delay says “browser, don’t even fetch this script until the user does something.” Useful for analytics, chat widgets, share buttons. Will break scripts that need to execute on page load (carousels, accordions, anything that hooks
DOMContentLoaded). - Combine says “merge multiple files into one.” Now mostly redundant in HTTP/2.
Apply Delay JS only on mobile devices
A subtoggle. Limits Delay JavaScript Execution to mobile only, leaving desktop as-is. Useful when a delay breaks desktop interactions but mobile is fine (or vice versa).Excluded scripts and rules
If a single JS file shouldn’t be deferred or delayed (commonly: jQuery on themes that depend on it loading immediately, or a payment gateway script):| Rule | What it covers |
|---|---|
| Excluded JavaScript Files | Skip these files from minification, combining, or defer. One pattern per line. |
| Excluded CSS Files | Same idea, for CSS. |
* wildcards.
A safe rollout
Don’t enable everything at once. The order we recommend:- Minify CSS (lowest risk).
- Test the site, including a checkout flow if you have one.
- Minify JavaScript.
- Test again, with a focus on interactive elements (sliders, modals, AJAX).
- Load JavaScript deferred.
- Test the homepage and a content-heavy page.
- Skip Combine on HTTP/2 stacks; otherwise enable last.
- Delay JavaScript Execution is the highest-risk toggle. Try it last and only if you’ve already squeezed everything else.
Common issues
Site looks unstyled or broken after enabling Minify CSS
Site looks unstyled or broken after enabling Minify CSS
Either a CSS file uses an unusual syntax minification can’t handle, or the file is dynamically generated with placeholders. Find the offending file via DevTools (the broken element’s computed styles will be missing) and add the file path to Excluded CSS Files.
Sliders, accordions, or popups stop working
Sliders, accordions, or popups stop working
Likely Delay JavaScript Execution is delaying a script that needs to run on page load. Disable Delay first to confirm. If that’s it, exclude the affected scripts via Excluded JavaScript Files (jQuery and theme JS bundles are common offenders) and re-enable Delay.
Forms or AJAX requests fail intermittently
Forms or AJAX requests fail intermittently
A nonce or CSRF token in a JS file may be getting cached after minification. Add the file to Excluded JavaScript Files, or move the token output into an inline script tag (which isn’t combined or minified).
PageSpeed score didn't improve after enabling everything
PageSpeed score didn't improve after enabling everything
Either the site’s bottleneck isn’t on the JS/CSS side (in which case X-Ray the slowest PHP), or HTTP/2 was already handling multiplexing. Use a waterfall diagnostic (DevTools → Network → Disable cache → reload) to see where the actual time is going.