Installing TailwindCSS in a WordPress Theme

TailwindCSS is an absolutely amazing front end CSS library that allows you to create stunning CSS layouts. Using TailwindCSS in your WordPress Theme will help add beauty and simplicity to your design. It will also make your theme scalable and easy to manage. Let’s get TailwindCSS added to our theme.

Pre-Requisite

I personally prefer to use Laravel Mix to manage the compilation of assets. It’s a beautiful wrapper for webpack that provides a ton of recipes for common libraries baked into it’s installation. Even though it’s “Laravel” mix, it works great in WordPress themes and plugins. If you need help installing Laravel Mix, you can read the quick recipe I threw together.

The other pre-requisite is that you have to have an NPM package already created for your theme. If you are using Underscores.me for your theme, this is already set up. Otherwise, make sure you follow the instructions to initialize an NPM package. NPM will have to be initialized in the root of your theme directory (/wp-content/themes/{yourtheme}). After that, we are good to go!

Step 1: Include TailwindCSS

The first step is to include TailwindCSS in your project. To do this, navigate to your theme directory and run the following command:

npm install tailwindcss

TailwindCSS is now installed on your theme! We just have to run a few configurations.

Step 2: Set Up Your Resources Directory

If you don’t have a resources or src directory created, I’d recommend creating one. This directory will contain all of your un-compiled assets. I’d recommend creating /wp-content/themes/{yourtheme}/resources/css. Now you have a place to store all of your un-compiled assets.

Step 3: Create theme.css

This file will be the landing point for compiling all of your CSS. In here you will be able to include all of your components, fonts, etc. We will also initialize everything we need to make TailwindCSS work.

In your /wp-content/themes/{yourtheme}/resources/css directory add the following file: theme.css. In that file, add this code:

@import "tailwindcss/base";

@import "tailwindcss/components";

@import "tailwindcss/utilities";

This will include the base styles for TailwindCSS when you compile.

Step 4: Create TailwindCSS Config File

In the documentation, this is labeled as optional, however, I find it to be extremely important. This file allows you to add your own custom colors, fonts, sizes, pretty much everything you need to customize TailwindCSS. Even if you don’t end up using it, I’d recommend having it created. To create this file, run:

npx tailwindcss init

In the root directory of your template, you should see a tailwind.config.js file which you can use to modify your TailwindCSS install (including adding the new Tailwind Typography plugin which is perfect for blogging).

Step 5: Install postcss-nested

When we installed Laravel Mix, the “recipe” for compiling PostCSS came included. PostCSS is a tool for processing CSS and is what tailwind prefers to use when compiling. They have a lot of plugins you can use, but the one I recommend and use often is postcss-nested. This plugin allows you to nest styles similar to what you would if using SASS.

I’d say 99% of the time we are using TailwindCSS as it was intended by using utility classes inline. However, that 1% where we abstract styles to a component, having the ability to nest styles is essential. To install the postcss-nested library, simply run:

npm install postcss-nested

Perfect! Now we have our tools installed! Let’s compile our styles!

Step 6: Adjust Laravel Mix to Compile Your Styles

So when we installed Laravel Mix into the theme, we created a webpack.mix.js file. This is the entry point for when we compile our assets. We will have our compiled Javascript and CSS rules in here. Let’s just assume we don’t have anything in this file as of now (if you do, you can just chain what we add to your existing compilation methods). Add the following code to this file:

const mix = require('laravel-mix');

mix.postCss('resources/css/theme.css', 'css', [
	require('tailwindcss'),
	require('postcss-nested')
])
.options({
	processCssUrls: false
});

What we are doing in this file is giving the instructions on how we want our CSS compiled. What we need to focus on is the the mix.postCss() method. This is what will compile our CSS. Let’s break it down.

The first parameter in mix.postCss() is the directory that contains our un-compiled CSS. In this case, it’s the resources/css/theme.css file we just created. This is the entry point for all of our TailwindCSS configuration. It will also include any overrides we may have.

The second parameter is the output directory for your compiled css. In this case, we are outputting the result of our compiled CSS to the /wp-content/themes/{yourtheme}/css directory.

Keep in mind, the outputted file will be theme.css as well. Feel free to override that if you prefer.

The third parameter is a list of modules to include with PostCSS. In this case it’s the tailwindcss module and the postcss-nested module. The order does matter for how you wish to compile your CSS. However, if you follow above, it’s currently in the right order. If you are adding more modules to the build chain, make sure you include them in the right order.

Finally, we have the .options() method passed with processCssUrls: false. I personally don’t want to deal with webpack trying to compile background assets and other URLs referenced within our styles. The choice is yours.

Step 7: Include the Compiled CSS in Your Theme

We did all the work, now let’s include the compiled output in our theme when it’s rendered! To do that, open up your functions.php file or wherever you manage your enqueued styles. Add the following to this file:

wp_enqueue_style( 'your-theme-styles', get_template_directory_uri().'/css/theme.css', array(), YOUR_THEME_VERSION );

There we go! Now you have TailwindCSS installed in your WordPress theme! From here, you can run any of the Laravel Mix build commands to compile your CSS depending on the environment!