How to add TailwindCSS to a Hugo website?

I have been using Tailwind for a while now, and I love it. It is a great tool for developers, but it can be a bit tricky to set up in Hugo if you've never done it before. In this post, I will show you how to add TailwindCSS to a Hugo website in 2023.

Requisites

First of all, you will need to install Hugo and Node.js. If you don't have them installed, you can follow the instructions in the official documentation:

• Install Hugo
• Install Node.js

Versions should be the latest ones if possible, I'm using Hugo v0.98.0+extended and Node.js v18.14.2 at the time of writing this post.

Create your site

Having Hugo and Node.js installed, you can create your site with the following command:

hugo new site my-site

Also, we will be working with themes, so we need to create a new theme for our site. You can do it by changing directories and executing the new theme command:

cd my-site
hugo new theme my-theme

You can of course replace my-site and my-theme with whatever you want. Make sure to link the theme to your site by editing the config.toml file:

baseURL = "https://example.org/"
languageCode = "en-us"
title = "My Hugo Site"
theme = "my-theme"

Installing Tailwind

Now that we have our site and theme created, we can install Tailwind.

The Hugo theme we created is located in the themes directory. We will need to install Tailwind in this directory. To do so, we will use the npm init command to create a package.json file. We pass the -y flag to accept all the default options. This file will contain all the information about our project, including the dependencies we will install.

cd themes/my-theme
npm init -y

Next, we will install Tailwind.

npm install -D tailwindcss

We pass the -D flag to install Tailwind as a development dependency.

You may notice that we are not installing PostCSS as you could have read in other tutorials. As of the time of writing, PostCSS is not required to use Tailwind with Hugo.

Setting up Tailwind

Next step is to set up Tailwind. We will need to create a tailwind.config.js file in the root of our theme. This file will contain all the configuration options for Tailwind.

npx tailwindcss init

This command will create a tailwind.config.js file that looks like this:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
};

For now, the only modification we will make is to add the content option. This option will tell Tailwind which files to look for Tailwind classes. We will add the layouts and content directories.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["content/**/*.md", "layouts/**/*.html"],
  theme: {
    extend: {},
  },
  plugins: [],
};

Configuring the CSS files

After that, we will need to create a css directory in the assets directory of our theme. This directory will contain the resources of our site, such as CSS, JavaScript, etc.

mkdir assets
mkdir assets/css

Next, we will create a main.css file in the css directory that looks like this:

@tailwind base;
@tailwind components;
@tailwind utilities;

We will need to add scripts to our package.json file to build the CSS file.

{
  "name": "my-theme",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "npx tailwindcss -i ./assets/css/main.css -o ./assets/css/style.css",
    "watch": "npx tailwindcss -i ./assets/css/main.css -o ./assets/css/style.css --watch"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "tailwindcss": "^3.3.1"
  },
  "description": ""
}

The build script will build the CSS file from main.css into style.css. The watch script will do the same, but it will also watch for changes and rebuild the CSS file when it detects a change. Very useful for development.

The last configuration we will need to do is to use style.css file in the layouts/partials/head.html file.

{{ $style := resources.Get "css/style.css" }}
<link rel="stylesheet" href="{{ $style.Permalink }}" />

Try it out!

Now that we have everything set up, we can try it out. We will need to run the watch script to build the CSS file and watch for changes. Remember that you need to run this command in the themes/my-theme directory.

npm run watch

We can now add Tailwind classes to our HTML files. For example, we can add a bg-red-500 class to a div element in our layouts/index.html file.

{{ define "main" }}
  <div class="bg-red-500">
    <h1>Hello, world!</h1>
  </div>
{{ end }}

If we now run Hugo (in the root of our site), we should see a heading with a red background.

hugo server

That should be it! You can now use Tailwind in your Hugo site. What we have done so far should be enough for most use cases. However, if you need to use a CMS, Tailwind could become a bit of a headache. In the next section, we will see how to use Tailwind with a CMS.

What if I need to change TailwindCSS classes in my CMS?

Let's say that you need to use a CMS to edit your site's content and styles. You'd end up with a situation like this:

<div class="bg-{{ .Params.bgColor }}-500">
  <h1>Hello, world!</h1>
</div>

In this case, you want the CMS user to be able to change the background color. Sounds reasonable, right? Well, the problem is that Tailwind will not be able to generate the classes beforehand.

To solve this problem, we will use Tailwind's safelist feature, which allows you to whitelist classes that Tailwind will not purge.

Open the tailwind.config.js file and add the following:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["content/**/*.md", "layouts/**/*.html"],
  theme: {
    extend: {},
  },
  plugins: [],
  safelist: [
    {
      pattern: /bg-(red|green|blue)-500/,
    },
  ],
};

If you're not familiar with regular expressions, this pattern will match the bg-red-500, bg-green-500, and bg-blue-500 classes so that Tailwind will not purge them. You can add as many patterns as you want.

You must use this feature with caution, as it can lead to bloated CSS files. However, it is a good solution for cases like the one we are dealing with.

That's all for this tutorial. I hope it was helpful. If you have any questions, feel free to contact me.