Documentation
Custom WordPress themes, now with Tailwind
Start quickly, or start from the very beginning
Quickstart
Installation
- Generate your theme
- Unzip the theme archive
- Move the resulting folder to
wp-content/themes
in your local development environment - Run
npm install && npm run dev
in the moved folder - Activate the theme in WordPress
Development
- Run
npm run watch
- Add Tailwind utility classes with abandon
Deployment
- Run
npm run bundle
- 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:
- 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.
- 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.
- 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.
- 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
- Custom WordPress themes, now with Tailwind
Start quickly, or start from the very beginning - WordPress and Tailwind: An introduction
Learn how Tailwind and WordPress work best together and when they should be kept apart - Generate your custom theme
The first step on your path to adding Tailwind to your WordPress development toolkit - Getting started with _tw
Install Tailwind, set up your development environment and run your first Tailwind builds - Tailwind plugins and more npm commands
Watch for changes, build for production and learn more about how _tw and Tailwind work together - Deploying to production
Put your new WordPress theme somewhere the rest of the world can see it