Fixing Oversized Stylesheets

Where the bytes in a big stylesheet come from

Hand-written CSS for a typical small-business site is rarely large. The kilobytes pile up in the build pipeline, where tools pull in far more than anyone chose line by line. When you open a bloated bundle and trace its contents, you usually find a mix of these:

Unused selectors on a single page are a related but separate problem. The unused CSS guide covers removing rules that nothing uses. This guide is about structure: what goes into each bundle, and which pages receive which bundle. How the finished file is delivered to the browser, including critical CSS and deferral, is in the render-blocking CSS guide.

Measuring what you are actually shipping

There are three sizes worth knowing for each stylesheet, and people often compare the wrong ones:

• Raw size: the file on disk after the build. This is what the browser has to parse.
• Transferred size: what travels over the network after gzip or Brotli. This is what affects download time.
• Size per page: the total of every stylesheet a given template loads. This is what a visitor actually pays for.

In DevTools, open the Network panel, filter to CSS and reload with the cache disabled. Hover the Size column, or turn on "Big request rows", to see both the transferred and the resource size. On the command line you can check the compressed size of a build output:

ls -l dist/assets/*.css
gzip -9 -c dist/assets/main.css | wc -c
brotli -c dist/assets/main.css | wc -c

To see what the bundle is made of, a CSS analyser such as Project Wallace reports the number of rules, selectors, declarations, duplicate values and embedded data: URIs. Simple searches also go a long way:

# How much of the file is base64 data?
grep -o 'data:[^)]*' dist/assets/main.css | wc -c

# Is the same selector compiled more than once?
grep -o '^\.btn-primary{' dist/assets/main.css | wc -l

If your build produces source maps as separate files, open the map in a text editor and look at the sources list. It names every partial and package that contributed to the output, which quickly shows whether an entire framework is in there.

The fix, step by step

Example: a trimmed Sass entry file

Here is the before and after for a fictional shop, Fernbrook Candles, whose single stylesheet had grown large because of a full framework import and a reset that was pulled in twice.

Before

// main.scss
@import "bootstrap";          // every component, whether used or not
@import "reset";              // also imported inside _shop.scss
@import "icons";              // full icon font, base64 embedded
@import "shop";
@import "blog";
@import "account";

After: a shared file plus per-area files

// shared.scss (loaded on every page)
// Framework foundations first, in the order the framework documents
@import "bootstrap/scss/functions";
@import "settings";                     // your variable overrides, outputs nothing
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";
// Then only the components the templates use
@import "bootstrap/scss/root";
@import "bootstrap/scss/reboot";
@import "bootstrap/scss/containers";
@import "bootstrap/scss/grid";
@import "bootstrap/scss/buttons";
@import "layout";                       // header, footer, navigation

// shop.scss (product and collection templates only)
@use "tokens";                          // shared variables as a module
@use "product-card";
@use "gallery";

// blog.scss (article templates only)
@use "tokens";
@use "article";

The file list above follows the partial-import approach in Bootstrap 5's documentation, which still uses @import for the framework's own files, so the shared file keeps that syntax while your own area files use @use. The exact list and order change between framework versions, so follow the documentation for the version you run. The principle is the same for any framework: pull in the foundations, then name each component explicitly, and let each template load only its own area file.

Platform notes

WordPress

Much of the weight on WordPress comes from plugins and page builders that enqueue their own full stylesheets on every page. You cannot restructure their builds, but you can stop their files loading where they are not used with wp_dequeue_style() in a child theme, and choose builders that output per-page CSS files. Block themes also offer an option to load block styles only for blocks present on the page. The WordPress CSS guide goes further.

Shopify

Online Store 2.0 themes already split component CSS into section-level files. Weight usually comes from apps and from custom code added to one catch-all file. See the Shopify CSS guide.

React, Next.js and other frameworks

Frameworks that bundle CSS per route do much of the splitting for you, as long as styles are imported by the components that use them rather than all at once in a root layout. A global stylesheet imported at the top of the app goes to every route. CSS-in-JS libraries that generate styles at runtime add JavaScript weight as well as CSS; the React and Next.js CSS guide compares the options.

Edge cases

• Cascade order after splitting. When one file becomes several, the order they load in changes which rule wins. A rule that used to come later in the single file may now load earlier. Check pages that load more than one bundle, and consider cascade layers to make the order explicit.
• Shared components used in two areas. If the product card appears on the blog as well as the shop, put it in the shared file or in its own small file, rather than copying it into both area bundles.
• Compression already on. If the server already sends Brotli, most of the transfer saving from minification is smaller than you might expect, because repeated text compresses well. The parse cost of the raw size still matters on slower phones.
• Third-party widget CSS. Chat, review and booking widgets often bring their own large stylesheet. Load the widget only on pages that need it, or after user interaction.

Stopping the bundle from growing back

1. Add a size check to your build or CI that compares each output file with a stored limit.
2. Review new dependencies for their CSS as well as their JavaScript before installing them.
3. Keep one owner for the shared stylesheet, so additions are a decision rather than a habit.
4. Re-run the CSS Checker after each release and compare the reported sizes with your baseline.
5. Keep variables and mixins in output-free files, and lint for the deprecated Sass @import.