Understanding tailwind safelisting in Hyvä theme

When working with Hyvä themes, one common source of confusion is how Tailwind generates CSS especially when classes are coming from CMS content.

Let’s break it down clearly.

Table of contents

The core problem: Why safelisting is needed

Tailwind generates CSS only for class names it detects in PHTML and XML files during the build process.

But CMS content (blocks, pages, Page Builder content) is stored in the database.

So if you use:

<p class="px-48">Hello</p>

inside CMS content, Tailwind will not see those classes during build and they will not be added in the final CSS.

That’s where safelisting becomes essential.

Tailwind v4 approach

Ror new Hyvä projects in Tailwind v4, Tailwind introduces a CSS-based directive:

1. Using @source inline()

Example:

@source inline("{sm:,md:,lg:}px-{48}");Hyvä-child-theme::web/tailwind/tailwind-source.css

This directive tells Tailwind to generate those utilities. When you run npm run build, Tailwind will process this directive and include the specified classes in the final CSS output.

  .sm\:px-48 {
    @media (width >= 40rem) {
      padding-inline: calc(var(--spacing) * 48);
    }
  }
  .md\:px-48 {
    @media (width >= 48rem) {
      padding-inline: calc(var(--spacing) * 48);
    }
  }
  .lg\:px-48 {
    @media (width >= 64rem) {
      padding-inline: calc(var(--spacing) * 48);
    }
  }

Supports regex patterns

• Supports pattern expansion
• Supports responsive variants

2. Using an external file in Tailwind v4

You can still include a text file:

@import "tailwindcss";
@source "safelist.txt";

Inside safelist.txt:

text-center
md:text-left
bg-red-500

Important limitation

• This only supports exact class names.
• You cannot use regex or pattern syntax inside the file. Tailwind will only detect literal class names.

Tailwind v3 approach (Legacy / Older Hyvä projects)

If you are maintaining an older Hyvä theme running Tailwind v3, you will see this pattern:

1. Config-based Safelist

module.exports = {
  content: [
    './templates/**/*.html',
    './**/*.phtml'
  ],
  safelist: [
    'text-center',
    'md:text-left',
    'bg-red-500',
  ]
}

Supports regex patterns

safelist: [
  { pattern: /^bg-opacity-/ },
  { pattern: /^-?[mp][trblxy]?-[48]$/ },
  { pattern: /^text-shadow/ },
]

This allowed scalable dynamic class generation directly in configuration.

2. Using an external file in Tailwind v3

Just like v4, you could also include a text file in the content array:

content: [
  './templates/**/*.html',
  './safelist.txt'
]

But again only exact class names were supported.

Happy building 🚀