Upgrading Your 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:

Terminal window
npx @tailwindcss/upgrade

Then install the new @tailwindcss/postcss package:

Terminal window
npm install @tailwindcss/postcss

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

Terminal window
npm uninstall postcss postcss-cli autoprefixer

Warning!: When deploying the site on Vercel, make sure to install the dependencies as regular dependencies instead of DevDependencies to avoid deployment error:

Log
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:

styles.css
@import "tailwindcss"; // New import method
@plugin "@tailwindcss/typography";


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

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:

postcss.config.mjs
{{- $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.