WordPress theme with Tailwind CSS support

In this article lets talk about Tailwind CSS support included in a theme supplied with WP BOX. For those, who is not familiar with Tailwind, this software allows you to minimise CSS usage in the project, as it is generating CSS files automatically, based on classes used in template files and optionally in other specified in the configuration file. With this approach, whenever you remove or redesign elements, old styles will also be removed automatically. Besides, minification and browser compatibility is also managed by the script during compilation.

I have described what features of Tailwind are implemented in WP BOX on page about frontend features, make sure to follow the link to see them.

How to start working with Tailwind

Tailwind CSS is installed as a node module, and NodeJS is created as a service during installation. Basic installation doesn’t install node modules, as they are only needed for development, thus you will have to run the following command to get them:

make npm ARGS="install"

This Makefile command will run the npm script inside a container. Here is what happens under the hood:
docker exec -w /var/www/site/web/app/themes/wp-box node-custom npm $(ARGS)

Alternatively you can invoke other npm commands, pass the second part of the command as ARGS string.

Theme folder contains package.json file, and after the packages will get installed, you will be able to use scripts from the package.json.

Again, the main command to start all scripts in the background is:

make start

Under the hood this command starts in parallel Tailwind CSS watch and compile job as well as other frontend pipelines.

To start only Tailwind, use this command instead:

make npm ARGS="run start-tailwind"

This command executes the following inside the NodeJS container:
npx tailwindcss -i ./styles/src/tailwind.css -o ./styles/dist/tailwind.css --watch=always --minify

Modifying existing Tailwind CSS configuration

If you want to modify existing configuration, consider applying modifications to the following files:

• web/app/themes/wp-box/tailwind.config.js – main configuration. Default setup includes defines for custom theme-related classes, list of files to parse Tailwind classes from and a script to sync settings with WordPress theme.json
• web/app/themes/wp-box/postcss.config.js – plugin configuration. Lets you setup post-processing in the compilation pipeline – autoprefixer, minification and other important things.
• web/app/themes/wp-box/styles/src/tailwind.css – main styles file which includes three layers mentioned below. Few global styles defined here directly.
• web/app/themes/wp-box/styles/src/tailwind.base.css – a file to define color scheme and other theme-related base styles.
• web/app/themes/wp-box/styles/src/tailwind.components.css – a file with reusable components, comes useful when you apply same styles for different elements, or just want to use shorter syntax with your layouts.
• web/app/themes/wp-box/styles/src/tailwind.utilities.css – file for defining custom utility classes. Use it if you didn’t find appropriate class in the documentation.

Mixing Tailwind CSS with other libraries and styles

Sometimes you might need to include styles from third-party libraries, or other custom CSS. There are few examples in the project – check the overrides for these core blocks:

• web/app/themes/wp-box/blocks-overrides/core/query-pagination – applies custom CSS to a class generated by WordPress
• web/app/themes/wp-box/blocks-overrides/core/code – enqueues Highlight JS library, which has it’s own classes

The recommended approach depends on the scope:

1. If you only need custom styles for one specific block, like Highlight JS, it makes sense to create them in the block-folder/assets/css/style.min.css, as in the examples above. This file is automatically enqueued only if the block is being used on the current page.
2. To apply custom styles globally, include them in the main file with Tailwind CSS, they will be compiled during the pipeline.

Do not modify the style.css file in the root directory of the theme. It is used only to pass WordPress check for a theme validity, and is not included in frontend.

Setting up VSCode IDE for Tailwind development

You can find a Tailwind CSS extension for VSCode in this file – .vscode/extensions.json

Also, your VSCode might suggest installing the extensions recommended by Workspace, do so and get them. After the installation, the extension will pick up settings from .vscode/settings.json, modify them as needed.

	"tailwindCSS.includeLanguages": {
		"html": "html",
		"javascript": "javascript",
		"css": "css",
		"php": "php"
	},