Hugo and Tailwind: peace at last (maybe)

In the beginning, there were the Hugo static site generator (SSG) and the Tailwind CSS styling framework. Separately, they were great; but, when you tried to put them together, things got complicated. Now, it appears, that’s been resolved. [Pinky-swear.]

Things first got weird between Hugo and Tailwind early in 2021, when v.2 of the latter included a just-in-time (JIT) compiler. At first, JIT was opt-in, then opt-out, and, since v.3, has been thoroughly baked into Tailwind. The problem has been that Tailwind/JIT just didn’t work all that smoothly with Hugo Pipes, Hugo’s built-in assets-handling pipeline, especially during development.

In November, 2021, I described a community-created, albeit somewhat convoluted, procedure that got Hugo to work with Tailwind v.2. However, only a few weeks later, the Tailwind folks brought out v.3. Again, the Hugo community adapted and, before long, I was able to explain a smoother procedure that worked if paired with Tailwind v.3.0.11 or newer (within v.3, of course; more on that later). Still, these solutions admittedly were hacks, necessary only because the Hugo team hadn’t yet managed to deliver an official fix for the glitch — albeit not for lack of trying, to be fair.

That changed with the recent release of Hugo v.0.112.0. Its major enhancement was a new build.cachebusters option that was targeted at, finally, solving the whole Hugo/Tailwind/JIT problem. Here’s a summary of how each product is to be configured as a result, given the example in that link.

• Hugo (in development mode):
  • Constantly updates the hugo_stats.json file, which automatically tracks the project's HTML tags, CSS classes, and IDs.
  • Uses the build.cachebusters settings, including for files “watched” by Tailwind, to tell Hugo when to update the dev server.
• Tailwind CSS:
  • “Watches” the hugo_stats.json file, as well as the other usual locations, to trigger JIT-based changes in the CSS output during Hugo’s development mode.

Update, 2023-06-05: The example code provided in the Hugo v.0.112.0 release notes seems to assume the use of Hugo Modules. I initially thought that, if not using them, you wouldn’t need the module settings to make this work. However, I’ve since learned otherwise.

And I can tell you that it works quite well. I’m currently working on a freelance project that pairs Tailwind v.3.x with suitably cachebusters-ed Hugo v.0.112.x (Hugo/Tailwind is the customer’s preferred arrangement), and the interaction between the two is just as it should be between Tailwind and any site-building platform.¹

Outstanding news, right? So why did I put “(maybe)” in the title? And why did I use the “Pinky-swear” wink-wink in the intro?

Well, it’s because Tailwind v.4 can’t be far off. Consider the cadence of the framework’s major version releases:

• v.1.0.0 — 2019-05-13.
• v.2.0.0 — 2020-11-18, eighteen months after v.1.0.0.
• v.3.0.0 — 2021-12-09, nearly thirteen months after v.2.0.0.

Thus, as of the initial publication of this post, it’s been nearly eighteen months since the release of v.3.0.0. Note also that Tailwind creator Adam Wathan said last November:

Goals for Tailwind CSS v4.0:

🤏 Simplify mental model, fewer framework-specific concepts
🪄 Less configuration, without less power
✂️ Fewer dependencies
⚡️ 10x faster

Aggressively defend against complexity, double down on robustness and stability 🤝

All of these, along with certain references in replies to various issues reports on the Tailwind CSS GitHub repository, suggest one should expect a v.4 release sooner rather than later.

The history of major Tailwind releases has been that each new one requires some juggling to make it work properly with Hugo. It’s been an “arms race” kind of thing. So, while Hugo v.0.112.x (and up) now gets along well with Tailwind v.3.x, we’ll have to wait to see what happens with future releases of Tailwind — and Hugo, for that matter.

1. I don’t know whether the aforementioned Hugo/Tailwind hacks still work but, in any event, you don’t need them any longer. ↩