Skip to content

Tailwind CSS Compilation

Hyvä CMS compiles Tailwind CSS for the content built in the Liveview Editor, so the utility classes used in components render without a full theme rebuild. That compilation can run in two places — in the admin browser or on the server — and you choose which in store configuration.

Compilation Strategies

Compilation can run in one of two ways, selected in store configuration. Both produce the same scoped output and render identically on the storefront — the difference is operational and affects inline page weight.

Strategy What it does Tailwind version Inline output Node.js
In-browser (default) Compiles Tailwind in the admin editor via the in-browser JIT compiler. v3 or v4 — one at a time, selected globally (not both simultaneously) Larger — ships every utility used in the content, including ones already in the theme bundle. Not required
Server-side (Node daemon) Compiles on the server against each theme's own Tailwind toolchain, returning only the delta — utilities not already in the theme's styles.css. Always each theme's own Tailwind version Smallest Required

Recommended for new projects: server-side compilation

For new projects, switch to server-side compilation. It produces the smallest inline CSS payload (typically a few hundred bytes per CMS entity instead of several KB), uses each theme's actual Tailwind configuration and version, and enables bulk recompilation. The only requirement is Node.js on the server.

The default remains in-browser so that existing sites keep working unchanged after upgrading — see Backward compatibility.

How It Is Installed

Both backends are pulled in automatically as dependencies of Hyvä CMS — there is no separate composer require or module:enable step:

  • hyva-themes/magento2-cms-tailwind-compiler — the server-side Node daemon.
  • hyva-themes/commerce-module-cms-tailwind-jit-bridge — the bridge that lets the Hyvä CMS Liveview Editor switch between the in-browser compiler and the daemon.

Because both are present on every Hyvä CMS install, switching from in-browser to server-side is just a configuration change plus having Node.js available on the server — nothing extra to install. The compiler daemon ships with its production Node dependencies bundled, so no npm install is required, and each theme's Tailwind dependencies are installed automatically on first compile if they are not already present. See Setting Up the Compiler Daemon for details.

Choosing the Strategy

Set the strategy at:

Stores → Configuration → Hyvä Commerce → Hyvä CMS → CMS Tailwind Compilation → Hyvä CMS Compilation Strategy

The setting is stored at config path hyva_cms_tailwind/hyva_cms_bridge/compilation_strategy, is global scope only, and defaults to in-browser. The same field is also available under Hyvä Themes → System → CMS Tailwind Compilation; both locations edit the same value.

Option Config value
In-browser (v3 or v4) in-browser (default)
Node Tailwind (server-side) daemon

In-Browser Compiler Version (v3 / v4)

When the strategy is in-browser, the In-Browser Tailwind Compiler Version field selects Tailwind v3 or v4. It defaults to v3.

Shared with native Magento PageBuilder

This version setting is shared with the native Magento CMS / PageBuilder compiler (Hyvä Themes → PageBuilder → CMS Tailwind Compilation → PageBuilder Tailwind Compiler). Changing it in either place changes both — the in-browser compiler always runs the same version for Hyvä CMS and native CMS content.

Per-theme in-browser configuration files (tailwind.browser-jit-config.js for v3, tailwind.browser-jit.css for v4) work exactly as documented for the JIT module — see Configuration. These files apply only to the in-browser compiler; server-side compilation ignores them and uses each theme's regular Tailwind config.

Using Server-Side Compilation

Set Hyvä CMS Compilation Strategy to Node Tailwind (server-side). The daemon is self-managing — it starts on first use, a watchdog cron keeps it healthy, and theme or Tailwind upgrades are picked up automatically. Node.js must be available on the server (in PATH or configured).

For daemon installation details, management options, production setup, and tuning, see Setting Up the Compiler Daemon. To rebuild every stored CMS Tailwind row in one pass after a theme or design-token change, see Recompiling CMS Content (bulk recompilation is only available in server-side mode).

Backward Compatibility

After upgrading, the strategy defaults to in-browser and the in-browser compiler version defaults to v3, so CMS content compiles exactly as it did before — no configuration change is required and existing content keeps rendering correctly. Moving to server-side (or to in-browser v4) is an opt-in change you make when ready.

How Compiled CSS Is Scoped and Stored

These details apply regardless of the chosen strategy — both produce the same output shape.

  • Scoped per entity. Compiled CSS is scoped with a wrapper selector in the form .hcms-{type}-{id} (for example .hcms-page-42), so content styles never leak into the rest of the page.
  • Isolated in a cascade layer. The compiled rules are emitted in a dedicated @layer hyva-cms-tailwind cascade layer, so CMS content styles cannot override theme styles purely through source order — the layer keeps them from conflicting with the rest of the page.
  • Stored per entity, theme, and edition. CSS is persisted for each entity, each theme, and each edition (draft, published, or scheduled).

Hyvä CMS vs Native Magento CMS

This page covers compilation for Hyvä CMS content edited in the Liveview Editor. Native Magento CMS content (PageBuilder and the WYSIWYG editor — CMS pages, blocks, and product/category descriptions) has its own, independent compilation setup documented under Server-Side CMS Tailwind Compilation. The two use separate bridges and separate strategy settings, but share the single in-browser compiler version setting described above.