Upgrading a Hugo Website from Tailwind CSS v3 to v4

I recently upgraded my site to use TailwindCSS v4. In this post, I’ll guide you through the upgrade process—just as I did for my own website, step by step… hopefully.

What’s Changed

There are a few breaking changes, as stated in their documentation. Some of these will change the way we structure the Hugo project.

• TailwindCSS v4 now automatically detects the content directory unlike the previous version, where we manually listed the layouts and contents files.

• Everything moves into your styles.css file; we no longer use the tailwind.config.js.

• The PostCSS plugin now lives in the new @tailwindcss/postcss package.

Upgrading to v4

Step 1: Installing new dependencies

To upgrade your project from v3 to v4:

npx @tailwindcss/upgrade

Then install the new @tailwindcss/postcss package:

npm install @tailwindcss/postcss

From here, you can safely remove postcss, postcss-cli, and autoprefixer from your package.json.

Step 2: Removing old files

Since tailwind.config.js is no longer used, migrate your custom styles to styles.css and add @import "tailwindcss". Here’s what it looks like now:

@import "tailwindcss"; // The new TailwindCSS import method

@plugin "@tailwindcss/typography"; // Import plugins

@theme {
  --color-custom-100: oklch(0.98 0.04 113.22); // Custom class
  --color-custom-200: oklch(0.94 0.11 115.03);
  ...
}

.example {
  @apply text-custom-400; // Custom styles
}

Step 3: Small adjustments (optional)

I renamed my postcss.config.js to postcss.config.mjs (this may not be necessary) to match the TailwindCSS docs, so we need to update the css.html with the new file name:

...
{{- $styles := resources.Get "css/styles.css" | postCSS (dict "config" "./assets/css/postcss.config.mjs") -}}
...

Step 4: Running the site

You can now run the site locally using hugo server and check for the applied TailwindCSS styles.

For those who are starting a new Hugo project with TailwindCSS v4, you can use the Hugo TailwindCSS Starter Template to quickly get up and running. This template is a clean starting point with TailwindCSS v4 already configured, so you can focus on building your content.