Your Hyva storefront’s compiled CSS is megabytes when it should be tens of kilobytes, and the cause is almost always the Tailwind build. Tailwind only keeps the classes it finds as plain text in your content paths, so a missing glob, a dynamic class name, or a dev build shipped to production is usually the culprit.
A bloated stylesheet is a Core Web Vitals problem: it is render-blocking weight on every page. The good news is that Tailwind is designed to produce tiny CSS, and when a Hyva build comes out huge, it is almost always a fixable configuration issue. This guide covers why the CSS gets big, how the content scan works, the dynamic-class trap, safelists, and the change in Tailwind v4. For the broader frontend, see our Hyva development services.
Why the dev build is huge, and the prod build is tiny
Tailwind’s development build is large on purpose. It generates every utility class so you can use any of them while building, which runs to roughly 3.6MB uncompressed, around 294KB minified and gzipped. That is fine for development and a disaster in production.
The production build solves this by scanning your templates and keeping only the classes you actually use, which typically drops the output to tens of kilobytes. On Hyva, you run the production build inside the theme’s Tailwind directory, with the watch build used only during development. Hyva’s generating CSS documentation covers the exact commands and the Node version each release needs.
The single most common cause of a bloated production CSS is simple: someone shipped the dev or watch build to production instead of running the production build. Check that first.
The content scan: Hyva must look in more than one place
Tailwind keeps a class only if it finds that class, as a complete string, in one of the files listed in its content configuration. On a plain site that is just your templates. On Hyva it is more, because a Hyva child theme inherits templates from places outside itself:
- Your child theme
.phtmltemplates. - The parent Hyva default theme in
vendor/. - The Hyva theme-module templates that ship UI.
If your content globs only scan the child theme, every class used by an inherited parent or module template gets stripped, and the storefront renders unstyled in places. The classic, alarming version of this: if the file containing your root selector is not in the content paths, the production build can strip essentially all of your CSS. Tailwind’s source-detection documentation explains how the scan works, and the v3 content configuration guide covers the glob syntax for older setups.
You can also exclude paths you have removed, like a disabled module’s templates, to avoid scanning dead files. The content list is the single most important thing to get right.
The dynamic class trap
The scanner reads your templates as plain text. It does not execute PHP or JavaScript. So any class name you build by concatenation is invisible to it:
// Stripped: Tailwind never sees "bg-red-500" as a whole string
class="bg-<?= $color ?>-500"
Because Tailwind only ever saw bg- and -500 as fragments, it does not generate bg-red-500, and the color is missing in production. This is one of the most common “it works in dev, breaks in prod” bugs on Hyva, because the watch build happens to include everything.
The fixes, in order of preference:
- Write complete class names. Use a lookup map so the full class exists as a literal string in the template: map
redtobg-red-500,greentobg-green-500, and so on. Now the scanner sees each whole class. - Put the classes in a scanned file. A plain
safelist.txtlisting the full class names, included in the content paths, keeps them. - Use the safelist option for classes that come from the database, CMS content, or runtime JavaScript and cannot be written literally anywhere.
Safelists, and keeping them narrow
A safelist tells Tailwind to always generate certain classes, even if it never finds them in a template. It is the right tool for genuinely dynamic classes, such as a color swatch class driven by a product attribute, or a status class injected by JavaScript.
The discipline is to keep it narrow. A broad safelist pattern re-inflates the bundle, which defeats the point. Limit patterns to the specific color families and shades you actually use, not every possible combination. The goal is to add back the handful of classes the scanner cannot see, not to re-enable thousands.
| Class origin | Safe approach |
|---|---|
| Static in a template | Nothing needed, the scanner finds it |
| Built by concatenation | Rewrite as full class names or a lookup map |
| From the database or CMS | Narrow safelist, only the classes in use |
| Injected by JavaScript | Safelist, or render the class server-side |
The Tailwind v4 change
Hyva 1.4 moved to Tailwind v4, which changes how all of this is configured. The config shifts from a JavaScript file toward CSS, and the way you safelist classes changes: rather than the old top-level safelist option, v4 leans on a source directive in CSS to force classes into the build. If you are upgrading, do not assume your v3 content and safelist config carries over unchanged. Our guide to upgrading to Hyva 1.4 and Tailwind v4 covers exactly what moves and how to scope the work. Confirm the current directive syntax against the Tailwind version your Hyva release ships, because this is an area that has changed recently.
How to diagnose a bloated build
When a Hyva storefront’s CSS is too big, work through it in order rather than guessing:
- Confirm which build shipped. Compare the deployed CSS file size against a fresh production build locally. If they differ by an order of magnitude, a watch or dev build went to production. This is the most common cause and the fastest to rule out.
- Check the content globs. Open the Tailwind config and confirm it scans the child theme, the parent theme in
vendor/, and the module templates. A production build that strips too much usually has incomplete globs. - Look for unstyled elements. If specific components render unstyled only in production, their classes are being purged, which points at either a missing glob or dynamically built class names in those components.
- Audit the safelist. If the CSS is too big rather than too small, an overly broad safelist pattern is often the reason. Narrow it to the families and shades actually in use.
- Re-measure. Rebuild and compare the output size, so you know the change worked before you ship it.
Most bloated or broken builds come down to one of these five, and the diagnosis takes minutes once you know where to look. The symptom (huge CSS, or missing styles in production) tells you which end of the content-and-safelist balance is off.
Why it matters for performance
A large CSS file is not a cosmetic problem. It is render-blocking bytes that every visitor downloads and the browser must parse before painting, which pushes out Largest Contentful Paint and hurts the exact Core Web Vitals a Hyva migration is supposed to improve. Our guide to reducing Largest Contentful Paint on a Hyva storefront covers the broader LCP picture, and a lean, correctly purged stylesheet is part of it. Getting the Tailwind build right is foundational to the speed Hyva promises, which is why it is one of the first things we check. For the full build and workflow, see our guide to Hyva theme development.
How CSS weight shows up on other platforms
Every platform has a version of the “too much CSS” problem, though the cause differs:
- Teams on Shopify development often carry heavy theme CSS and app-injected styles rather than a purge misconfiguration.
- BigCommerce development and Shopware development each have their own theming stacks, with their own sources of CSS bloat.
What is specific to Hyva and Tailwind is that the fix is deterministic: scan the right files, write real class names, and keep the safelist tight, and the output is tiny by construction. The team at Bemeir tunes these builds on production Hyva stores, and our technology partners include the tooling that measures the result. Learn how we work about Bemeir, and see our Magento development services for the platform behind the theme.
FAQ
Why is my Hyva Tailwind CSS so large?
Almost always because the development or watch build was shipped instead of the production build, or because the content globs are scanning the wrong files. The dev build generates every utility class, around 3.6MB uncompressed. The production build scans your templates and keeps only the classes you use, dropping the output to tens of kilobytes.
What files should Tailwind scan on a Hyva theme?
Your child theme templates, the parent Hyva default theme in vendor/, and the Hyva theme-module templates, because a child theme inherits markup from all of those. If the content globs only cover the child theme, classes used by inherited templates are stripped, and the storefront renders unstyled in places.
Why do some classes disappear in the production build?
Because Tailwind scans templates as plain text and does not run your code. A class built by concatenation, like bg-${color}-500, is never seen as a whole string, so it is not generated. Write full class names, use a lookup map, or add the classes to a safelist.
What is a Tailwind safelist and when do I need one?
A safelist forces Tailwind to generate specific classes even when it cannot find them in a template. You need it for classes that come from the database, CMS content, or runtime JavaScript. Keep it narrow and limited to the classes actually in use, because a broad safelist re-inflates the bundle.
Does Tailwind v4 change the Hyva build?
Yes. Hyva 1.4 uses Tailwind v4, which moves configuration toward CSS and changes how classes are safelisted, favoring a source directive over the old safelist option. A v3 config does not carry over unchanged, so review the content and safelist setup when upgrading.
A lean stylesheet is a configuration, not a compromise
Tailwind produces tiny CSS when its build is configured correctly, and on Hyva that means scanning the right templates, writing real class names, and keeping the safelist tight. A bloated stylesheet is almost always a fixable build problem, not a limitation. Bemeir is the USA’s first Hyva Gold Partner, and we tune these builds so the storefront ships the bytes it needs and nothing more. If your Hyva CSS is heavier than it should be, the fix is almost always in the content globs and the safelist, not in the markup itself.
