I pulled Tailwind v4 into a Hugo project expecting the usual quick wire-up, ran hugo server, and got a page with zero styling whatsoever. Not broken styling — none. Console wasn’t even throwing anything useful, just a build that completed and produced HTML with no classes applied. My first move was pasting in an old postcss.config.js from a v3 project out of habit. That crashed the build instantly, which at least told me something had actually changed — I just didn’t know what yet.
What Actually Changed Between v3 and v4 #
The short version: Tailwind v4 dropped tailwind.config.js completely. Configuration now lives inside your CSS file itself, through @import, @theme, and @source directives, processed by Lightning CSS — a Rust-based engine replacing the old PostCSS pipeline. Hugo, on its side, ships native support for the Tailwind CLI through css.TailwindCSS, which sounds like it should make this trivial. It mostly does, once you know where the two systems actually need to agree with each other.
| Feature | Tailwind v3 | Tailwind v4 |
|---|---|---|
| Config | tailwind.config.js |
CSS-native (@theme, @source) |
| Engine | PostCSS / JS | Lightning CSS (Rust) |
| Content scanning | Explicit content: [] paths |
Automatic, plus @source |
| Hugo integration | External PostCSS pipe | Native css.TailwindCSS |
Step 1: Get the CLI Installed #
npm install --save-dev tailwindcss @tailwindcss/cliConfirm you’ve actually got an assets/ directory at your project root — Hugo’s resource pipeline only touches files living inside that tree, so if your CSS is sitting somewhere else, nothing downstream here will find it.
Step 2: Build the Entry File #
No @tailwind base; / components; / utilities; anymore — that syntax is gone.
mkdir -p assets/css && nano assets/css/main.css@import "tailwindcss";
@theme {
--font-sans: "Inter", system-ui, -apple-system, sans-serif;
--font-mono: "Fira Code", monospace;
--color-brand-dark: #09090b;
--color-brand-accent: #3b82f6;
}
@source "hugo_stats.json";That last line is where I’d stop you if you were about to copy @source "../../layouts" and @source "../../content" from somewhere — that’s not actually how this scanner works in this pipeline. Tailwind isn’t reading your raw template files here; it’s reading the list of classes Hugo already rendered into HTML, which lives in hugo_stats.json. Point @source at that file directly and it picks up every class your templates actually produced, shortcodes included, without you having to separately enumerate every directory that might contain a class name.
Step 3: Get Hugo Actually Generating That Stats File #
This is the step most likely to go stale depending on which Hugo version you’re running, because the config key changed. Older setups use:
[build]
writeStats = trueCurrent Hugo versions moved this under its own block:
[build]
[build.buildStats]
enable = trueEither works depending on your version, but if you’re on anything recent, use buildStats.enable — it’s the one that’s actually documented going forward.
Getting the stats file generated is only half of it, though. You also need Hugo to actually watch it for changes, or edits to your templates won’t invalidate your compiled CSS and you’ll be staring at a page that didn’t pick up your new class. That requires a module mount, which the cachebuster rules alone don’t give you:
[[module.mounts]]
source = "assets"
target = "assets"
[[module.mounts]]
source = "hugo_stats.json"
target = "assets/notwatching/hugo_stats.json"
disableWatch = true
[[build.cachebusters]]
source = 'assets/notwatching/hugo_stats\.json'
target = 'css'
[[build.cachebusters]]
source = '(postcss|tailwind)\.config\.js'
target = 'css'Without that mount, the cachebuster rule has nothing real to watch, and you end up debugging a cache that never invalidates when it should.
Step 4: Wire Up the Partial #
{{ $css := resources.Get "css/main.css" }}
{{ if $css }}
{{ $opts := dict "minify" (not hugo.IsDevelopment) }}
{{ $styles := $css | css.TailwindCSS $opts | fingerprint }}
<link rel="stylesheet" href="{{ $styles.RelPermalink }}" integrity="{{ $styles.Data.Integrity }}" crossorigin="anonymous">
{{ end }}resources.Get grabs the file off Hugo’s virtual mount. css.TailwindCSS pipes it through the CLI, which runs Lightning CSS under the hood to resolve your @imports and prune anything unused. fingerprint tacks on a content hash for both cache-busting and the SRI integrity attribute you see on the final tag.
Step 5: Security Config, Done Right #
If you’re building inside anything sandboxed — GitHub Actions, Cloudflare Pages, a locked-down Docker image — Hugo’s security policy can block the Tailwind CLI from running at all, or from reading files it needs. The fix isn’t wrong in spirit, but how you write it matters:
[security.exec]
allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^git$', '^node$', '^npx$', '^postcss$', '^tailwindcss$']
[security.node.permissions]
allowRead = ['.', 'assets', 'node_modules']The thing to actually watch for here: security.exec.allow doesn’t merge with Hugo’s built-in defaults — it replaces them. Write a short list with just tailwindcss and a couple others, and you’ve just revoked permission for everything Hugo normally allows by default, including git, which a lot of themes quietly depend on for commit-based last-modified dates. If you’re overriding this at all, write the full list back out rather than trimming it down to only what you think you need right now.
One more thing worth knowing if you’re setting this up fresh: earlier Hugo releases — specifically 0.162 through 0.164 — shipped with tailwindcss included by default under the Node permission that allows spawning child processes, and because Tailwind’s config loading can execute code at startup, that combination was a real RCE path, patched in 0.165.0. If you’re not already on 0.165 or newer, update Hugo itself before you touch any of this config — the vulnerable default existed before you wrote a single line here.
Step 6: Run It #
hugo server --disableFastRender--disableFastRender matters more than it looks here — Hugo’s fast render mode can skip full page rebuilds in ways that occasionally miss a CSS recompile when you’re actively iterating on Tailwind classes, so during active style work it’s worth the slightly slower rebuild to actually see what you changed. Drop it once you’re past the iteration phase. For the real build:
hugo --minifyMinified, fingerprinted, pruned down to only the classes your markup actually used — and this time, actually working, because the pieces that needed to agree with each other now do.