How to create a WordPress theme using TailwindCss

In this post, I’ll show you how you can set up TailwindCss in your WordPress theme and have an awesome and efficient workflow.

TailwindCss is A utility-first CSS framework, Tailwind CSS is a highly customizable, low-level CSS framework that gives you all of the building blocks you need to build bespoke designs without any annoying opinionated styles you have to fight to override.

To begin creating your theme, we will use underscores starter theme. Underscores is a starter theme meant for hacking so don’t use it as a Parent Theme. It has all the barebones needed for creating an awesome theme.

First, you need to set up WordPress locally ideally with some dummy data. I recommend using the FakerPress plugin.

Creating the starter theme

To create the starter theme you can go to underscores site and generate it or you can use the following command (WP_CLI)

$ wp scaffold _s wptailwindtheme --activate --theme_name=”WP Tailwind Theme” --author=”Rijad Husic” --author_uri=”https://rijad.dev”

This will create your theme under wp-content/themes/wptailwindtheme and set that theme as active

Adding Tailwind CSS

After verifying this we can move to the next step and that’s adding tailwindcss to our theme.

I’ll use yarn for that but feel free to use npm if you want.

Navigate to your theme directory and add tailwindcss to the theme using the following command

$ cd wp-content/themes/wptailwindtheme

$ yarn add tailwindcss -D

The -D means as a development dependency

It should take a couple of seconds and after that, we get a package.json file in our theme alongside node_modules directory and yarn.lock file (package.lock file if you used npm).

Adding Laravel-Mix

After installing tailwind we need something to build it. There are couple of choices available like gulp and grunt. We will use laravel-mix, the name can be misleading but it can be used outside of laravel just fine.

To add laravel-mix to the theme simply run

$ yarn add laravel-mix -D

After that create an empty webpack.mix.js file in your theme directory.

We will use it to tell laravel-mix what to do.

const mix = require('laravel-mix');
mix.postCss('./resources/css/app.css', './public/css/app.css',[
  require('postcss-import'),
  require('tailwindcss'),
  require('postcss-nested')
]).options({
  processCssUrls: false
});
mix.browserSync({
  proxy: 'wordpress.test',
  notify: false
});

Adding additional dependencies

$ yarn add postcss-import -D

$ yarn add postcss-nested -D

I use postCss so I added postcss-import and postcss-nested in order to solve the importing problem and postcss-nested to be able to nest your styles. Which is nice for markdown but I’ll show that later on.

Init tailwind config

To init tailwind and create the tailwind config file run

$ ./node_modules/.bin/tailwind init tailwind.config.js

With this, you get an empty tailwind.config.js file. You can leave it like this and add stuff as you go but I suggest adding the Tailwind’s default configuration.

We will modify this a bit but more on that later.

Adding run scripts

In order to build your theme, you’ll need to add the following scripts to your package.json, simply replace the scripts section at the end with the following

"scripts": {
  "dev": "yarn run development",
  "development": "NODE_ENV=development node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
  "watch": "yarn run development --watch",
  "prod": "yarn run production",
  "production": "NODE_ENV=production node_modules/webpack/bin/webpack.js --no-progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js"
}

NOTE: this will work if you are on Mac or Linux. If you are on windows you will probably need to modify the commands a bit.

Adding syles

Remember we specified where your styles will be in the webpack.mix.js file and where will it build the public compiled CSS.

Create an app.css under

resources/css/app.css

Add the following to it

@import "tailwindcss/base";
@import "./custom-base-styles.css";

@import "tailwindcss/components";
@import "./custom-components.css";

@import "tailwindcss/utilities";
@import "./custom-utilities.css";

This will include the tailwind base styles and give you an option to write your own.

So create those in the same directory as app.css

• custom-base-styles.css
• custom-components.css
• custom-utilities.css

Now to check that everything is okay run

$ yarn run dev

You should now have your generated public/css/app.css file

Using the styles

In order to use the generated style, we need to go to functions.php and locate wp_enqueue_style.

Replace that line

wp_enqueue_style( 'wptailwindtheme-style', get_stylesheet_uri(), array(), _S_VERSION );

Now we can remove the default styles from style.css. Remove everything except the comments on the top witch is the theme info shown in the admin panel.

Verifying styles

Now we can go to header.php and simply add a text-gray-700 class to the body tag like so

<body <?php body_class('text-gray-700'); ?>>

And you should have a gray text on the frontend which confirms that the styles are working correctly.

Changing fonts

In order to change fonts go to tailwind.config.js file and find the fontFamily section, simply add whatever font you want as the first option.

To add custom fonts, for example, Inter font. Download the font, add a fonts directory in resources, and put the fonts you want to use there.
In this example, we will use Inter-upright-var.woff2. So copy it to resources/fonts/Inter-upright-var.woff2

Now go to the custom-base-styles.css and paste the following

@font-face {
  font-family: "Inter var";
  font-weight: 100 900;
  font-style: normal;
  font-display: swap;
  src: url('../../resources/fonts/Inter-upright-var.woff2') format("woff2");
}

Set ‘Inter var’ as the first font in tailwind.config.css and execute the yarn run dev command.Now the applied font should be Inter var font.

Posts markdown

To add basic markdown for your posts go to custom-base-style.css and add the following

.markdown {
  @apply text-gray-700 leading-relaxed;
  
  * {
    @apply mt-2;
  }
  > * + * {
    @apply mt-6;
  }
  h1 {
    @apply text-3xl font-bold text-gray-900 leading-tight;
  }
  a {
    @apply text-gray-900 underline;
  }
  ul {
    @apply list-disc pl-6;
    li + li {
      @apply mt-2;
    }
  }
  .wp-block-preformatted {
    @apply bg-gray-100 border border-gray-200 text-gray-900 text-sm font-mono rounded p-3 mt-2 whitespace-pre overflow-auto;
  }
}

I’ll provide you with the full code at the end of the post so no need to rewrite this code.

Now go to single.php and add markdown class to the main tag and you should have some basic markdown and can extend it further from here.

Purge unused CSS

In order to purge (remove), unused CSS from your public style go to the tailwind config file and replace the purge [] line with the following

module.exports = {
  purge: {
    content: ['./template-parts/*.php', './inc/*.php', './*.php'],
    options: {
      whitelist: [],
    }
  }
}

Where I specified the template paths that will be checked for used classes and then simply run

$ yarn run prod

This will minify your style and add only the used classes so the end result will be really small CSS file just a few Kb in size.

You can also use

$ yarn watch

While developing this will recompile the styles as you change them and also reload your browser as I added the browserSync to the mix.

Github repository

I added this theme to my GitHub so you can download it and check it out https://github.com/rijadhusic/WP-Tailwind-Theme

Happy hacking and now go and create an awesome WordPress theme!