Table of Contents & Menu
On this page
Navigation

Updating to Tailwind CSS v4

Since Hyvä 1.4.0

While older Hyvä versions can be upgraded, Hyvä 1.4.0+ officially supports Tailwind CSS v4 out-of-the-box.

Introduction

Tailwind CSS v4 is a complete rewrite with a new, significantly faster high-performance engine called Oxide.

It transitions from a PostCSS plugin to a standalone tool, moving configuration from tailwind.config.js to a CSS-first approach using the @theme directive.

Prerequisites

  • Node.js: Version 20+ recommended.
  • Browser Support: Tailwind v4 requires modern browsers (e.g., Safari 16.4+, Chrome 111+, Firefox 128+) due to its use of modern CSS features. For older browser support, remain on Tailwind v3.

Hyvä Upgrade Steps

Copy the updated web/tailwind folder

We recommend upgrading by copying the `web/tailwind` folder from the new Hyvä Default Theme.
Always create a backup first.

Alternative: Manual Upgrade Steps

Follow these steps for a manual upgrade:

1. Update Dependencies

  1. Navigate to your theme's web/tailwind folder.
  2. Remove PostCSS Node packages: 
    npm uninstall postcss postcss-import postcss-preset-env
  3. Delete the postcss.config.js file.
  4. Remove old Tailwind CSS plugins: 
    npm uninstall @tailwindcss/forms @tailwindcss/typography
    These are replaced by the @hyva-themes/hyva-modules package.
  5. Update @hyva-themes/hyva-modules to the latest version: 
    npm install @hyva-themes/hyva-modules@latest
  6. Update Tailwind CSS: 
    npm install tailwindcss@latest
  7. Add the Tailwind CSS CLI: 
    npm install @tailwindcss/cli@latest
  8. Update the scripts section in your package.json: 
    "scripts": {
    "start": "npm run watch",
    "generate": "npx hyva-sources && npx hyva-tokens",
    "prewatch": "npm run generate",
    "watch": "npx tailwindcss -i tailwind-source.css -o ../css/styles.css --watch",
    "browser-sync": "npx browser-sync start --config ./browser-sync.config.js",
    "prebuild": "npm run generate",
    "build": "npx tailwindcss -i tailwind-source.css -o ../css/styles.css --minify"
},

2. Update CSS Entrypoint

Replace old @import statements in your main CSS file (web/tailwind/tailwind-source.css) with the new ones.

tailwind-source.css for Tailwind 4 
/**
 * Welcome to your Hyvä Theme!
 *
 * If you're new to TailwindCSS, get started with the official documentation:
 * https://tailwindcss.com/
 *
 * For Hyvä-specific topics like CSS merging from modules or using design tokens,
 * refer to the Hyvä Themes documentation:
 * https://docs.hyva.io/hyva-themes/working-with-tailwindcss/index.html
 */

@import "@hyva-themes/hyva-modules/css";
@import "tailwindcss" source(none);
@source "../../**/*.phtml";
@source "../../**/*.xml";

/* Custom styles */
@import "./base";
@import "./components";
@import "./theme";
@import "./utilities";

/* Import generated styles for Hyvä Compatible Modules and Design Tokens */
@import "./generated/hyva-source.css";
@import "./generated/hyva-tokens.css";

@theme {
    --color-bg: var(--color-slate-50);
    --color-fg: var(--color-slate-950);
    --color-fg-secondary: var(--color-slate-600);
    --color-surface: var(--color-white);
}

Warning

Tailwind v4 requires specific CSS import paths; the ./ prefix is now mandatory. You can exclude index.css if it's in the import folder.

Before proceeding, back up your current styles by creating a backup folder in web/tailwind and copying your styles into it.

Then, copy all folders (except node_modules) from the Hyvä Default Theme's web/tailwind directory into your theme's web/tailwind directory.

3. Migrate Configuration to CSS

Tailwind v4 shifts configuration from tailwind.config.js to your CSS file using the @theme directive.

A new config file allows you to maintain a similar syntax for colors and spacing via design tokens.

What are Design Tokens?

Learn more about Design Tokens in our FAQ.

First, create the hyva.config.json file by running this command in your web/tailwind folder:

npx hyva-init

The Hyvä Default Theme uses a primary color, which you'll need to add to hyva.config.json.

Default hyva.config.json values:

{
  "tailwind": {
    "include": [],
    "exclude": []
  },
  "tokens": {
    "values": {
      "color": {
        "primary": {
          "lighter": "oklch(52% 0.2 265)",
          "DEFAULT": "oklch(46% 0.2 265)",
          "darker": "oklch(28% 0.2 265)"
        },
        "secondary": {
          "lighter": "oklch(72% 0.2 150)",
          "DEFAULT": "oklch(53% 0.15 150)",
          "darker": "oklch(39% 0.1 153)"
        },
        "on": {
          "primary": "#fff",
          "secondary": "#fff"
        }
      },
      "form": {
        "radius": "var(--radius-lg)",
        "stroke": "var(--color-slate-400)",
        "active-color": "var(--color-primary)"
      }
    }
  }
}

Once hyva.config.json is created, restore your custom styles from the backup folder.