Skip to content

Documentation

Custom WordPress themes, now with Tailwind

Start quickly, or start from the very beginning

Quickstart

Installation

  1. Generate your theme
  2. Unzip the theme archive
  3. Move the resulting folder to wp-content/themes in your local development environment
  4. Run npm install && npm run dev in the moved folder
  5. Activate the theme in WordPress

Development

  1. Run npm run watch
  2. Add Tailwind utility classes with abandon

Deployment

  1. Run npm run bundle
  2. Upload the resulting zip file to your site using the “Upload Theme” button on the “Add Themes” administration page

Have more complex deployment requirements? I’ve received reports of successful deployments via GitHub Actions, Envoyer, Deployer and Capistrano. For more details, please see the deployment documentation.

Overview

Here’s a quick summary of what you’ll need to do to integrate Tailwind with WordPress:

  1. Set up a local development environment: If you already have a local development environment for WordPress, you should be all set. If not, Delicious Brains has you covered with articles on your local development options, both CLI- and GUI-based.
  2. Create a custom theme: This is where _tw comes in! Generate your custom theme, install it in a local WordPress environment, and use utility classes to style it any way you like.
  3. Create a production build: Once you’re happy with how your site looks, you’ll create a production build, locking in the subset of Tailwind utility classes needed to style your WordPress theme. (Not sure what this looks like in practice? Tailwind’s documentation has an in-depth look at their approach to class detection.
  4. Deploy your production build: When you’re ready to go live, you’ll upload your theme to the web host of your choice.

After deploying to production, you shouldn’t plan to use new and arbitrary utility classes within the WordPress editor. The process of creating a production build will lock in a fixed subset of utility classes, so you need to prepare in advance (likely by safelisting classes) if there are specific utility classes you’d like to make available within the editor that you don’t already use elsewhere on the site.

Next Up

WordPress and Tailwind: An introduction
Learn how Tailwind and WordPress work best together and when they should be kept apart

All Documentation