March 31, 2025·1 min read

Upgrade Your Hugo Site to Tailwind CSS v4

A step-by-step guide to migrating a Hugo site from Tailwind CSS v3 to v4 with the new CSS-first configuration.

There is a new major version of Tailwind CSS that includes several changes. Here’s how to update a Hugo site from Tailwind CSS v3 to v4 and optimize the build process.

Important: Do a full backup of your project or create a new branch before starting.

1. Upgrade the Tailwind package

Start using the Tailwind upgrade tool from a v3 project:

npx @tailwindcss/upgrade

This updates package.json to Tailwind CSS v4 and converts your main CSS file to the new import format.

If your CSS imports tailwind.config.js, remove that line and adapt to the new config format.

2. Change Hugo Pipes

Replace the PostCSS pipes with @tailwindcss/cli and the new css.TailwindCSS Hugo pipe.

2.1. Install the Tailwind CSS CLI

npm install -D @tailwindcss/cli

Create a new css.html partial in layouts/partials/:

{{ with (templates.Defer (dict "key" "global")) }}
  {{ with resources.Get "css/styles.css" }}
    {{ $opts := dict "minify" hugo.IsProduction "inlineImports" true }}
    {{ with . | css.TailwindCSS $opts }}
      {{ if hugo.IsProduction }}
        {{ with . | fingerprint }}
          <link
            rel="stylesheet"
            href="{{ .RelPermalink }}"
            integrity="{{ .Data.Integrity }}"
            crossorigin="anonymous"
          />
        {{ end }}
      {{ else }}
        <link rel="stylesheet" href="{{ .RelPermalink }}" />
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

2.2. Update your CSS

Change the css/styles.css path to point to your assets folder. Then use this partial in your head:

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <meta author="Author Name" />
  <meta name="description" content="{{ .Description }}">
  <title>{{ .Site.Title }}</title>
  {{ partial "head/css.html" . }}
</head>

3. Hugo Config

Add this build and module config to your Hugo config:

[build]
  [build.buildStats]
    enable = true
  [[build.cachebusters]]
    source = 'assets/notwatching/hugo_stats\.json'
    target = 'css'
  [[build.cachebusters]]
    source = '(postcss|tailwind)\.config\.js'
    target = 'css'
[module]
  [[module.mounts]]
    source = 'assets'
    target = 'assets'
  [[module.mounts]]
    disableWatch = true
    source = 'hugo_stats.json'
    target = 'assets/notwatching/hugo_stats.json'

4. Update Plugins

If you use plugins like @tailwindcss/typography or DaisyUI, update them to the latest version:

@plugin "@tailwindcss/typography";

5. Final CSS

After the upgrade, your CSS file should look like this:

@import "tailwindcss";

@source 'hugo_stats.json';

@plugin "daisyui" {
  themes:
    light --default,
    dracula --prefersdark;
}

@plugin "@tailwindcss/typography";

@theme {
  --font-ubuntu: ubuntu-regular;
}

@layer base {
  *,
  ::after,
  ::before,
  ::backdrop,
  ::file-selector-button {
    border-color: var(--color-gray-200, currentColor);
  }
}

You can now safely remove the postcss and autoprefixer packages.

Tags:#hugo#tailwindcss#css