Upgrading a Hugo Site to Tailwind CSS 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.

Upgrading to v4

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.

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.

npm uninstall postcss postcss-cli autoprefixer

Error: error building site: POSTCSS: failed to transform "/css/styles.css" (text/css):
Error: Loading PostCSS Plugin failed: Cannot find module '@tailwindcss/oxide-linux-x64-gnu'

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:

1
@import "tailwindcss"; // New import method
2

3
@plugin "@tailwindcss/typography";
4

5
@theme {
6
  --color-custom-100: oklch(0.98 0.04 113.22);
7
  --color-custom-200: oklch(0.94 0.11 115.03);
8
  ...
9
}

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.