Tailwind CSS with Timber for WordPress Theme Development

By Joey

Filed under WordPress Theme Development

A major frustration with WordPress theme development is the ugly-and-frustrating syntax mess of PHP templates.

Timber came along and tapped into a PHP templating language called Twig. Suddenly, no more messy templates. Yay!

If you are new to Timber, I created a video showing you how to get started with WordPress theme development using the Timber plugin and starter theme.

Tailwind is a utility-first approach to CSS, which takes advantage of PostCSS.

I was very skeptical of Tailwind CSS at first, but once I watched the screencasts – I started to understand how CSS can be handled this way, as a design API for your site.

So I created another video adding to the Timber theme development workflow to incorporate Tailwind CSS.

Step-by-step Guide for adding Tailwind CSS within Timber starter theme for WordPress theme development

Tailwind is a package that is available through NPM. Create a package.json file by running the command npm init -y in the root of your WordPress theme folder from your terminal.

Then, run npm i tailwindcss postcss-cli autoprefixer. This installs Tailwind, PostCSS and Autoprefixer. Both Tailwind and Autoprefixer are plugins handled by the PostCSS workflow.

Next, run npx tailwind init This creates an empty tailwind config file – which you can use at a later time to extend or override default Tailwind settings. (see documentation)

Then, create a postcss.config.js file in the root of your theme directory. This is where we will tell PostCSS to use Tailwind and Autoprefixer as plugins.

In postcss.config.js, put the following code:

module.exports = {
    plugins: [
        require('tailwindcss'),
        require('autoprefixer'),
    ]
}

Create a tailwind.css file in a static/css/ directory. (Note: This is just where I chose to place the file, eventually the CSS and tailwind-specific code in this file will be compiled to our final style.css file.)

In the newly created tailwind.css file, paste the following code:

 /*
 Theme Name: Your Theme
 Theme URI: https://example.com/theme
 Author: Your Name
 Author URI: Your website
 Description: Description
 Version: 0.1
 License: GNU General Public License
 License URI: https://www.gnu.org/licenses/gpl.html
 Tags: 
 Text Domain: 
 */

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

In our package.json file, we can create a build script to process our Tailwind CSS file by PostCSS, and output the result to our style.css file in the root of our theme directory:

"scripts": {
     "build": "postcss static/css/tailwind.css -o style.css"
 }

Back in your terminal, type npm run build The script will run and output all new CSS to your style.css file. (Note: for now, the file will be huge!. But that is only because it contains every utility class available in Tailwind, not just the classes you will end up using in your theme. We will address this with PurgeCSS.)

Install purge by running the following command: npm i @fullhuman/postcss-purgecss

Next, set up purge in your postcss.config.js file. For example:

 module.exports = {
   plugins: [
     require('tailwindcss'),
     require('autoprefixer'),
     require('@fullhuman/postcss-purgecss')({
         content: [
             '**/*.twig'
         ],
         defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || []
     })
   ]
 }

PurgeCSS uses regular expressions to compile a list of CSS classes you are using in your templates, then removes unused classes from your final compiled CSS.

Each template language and project build structure will be slightly different. The above example works for twig templates, which is what Timber uses. I found this regular expression for Twig and PurgeCSS.

Now, when you run your build script, you should have a very small CSS file compared to one that contains all of Tailwind’s classes. You can use everything Tailwind has to offer out-of-the-box in development, but be sure to use PurgeCSS when pushing to production.

Ship fast, responsive websites with confidence.

Level-up your front-end skills through weekly emails and project-based courses.