Kirby meets Tailwind CSS
This is a walkthrough on how to install and use Tailwind CSS v4 with Kirby.
Preparation
Before we start, you need to install Node.js for the build process on your client machine (or on the machine where you want to use Tailwind CSS). The latest version, which also includes npm (Node package management) can be downloaded from the official Node.js website. You can test successful installation by opening a terminal window and typing the following two commands:
node --version
npm --version
We use a Kirby Starterkit or Plainkit to get started, and create a new /src
folder in the project's root, so that our folder structure looks like this.
- .htaccess
- composer.json
- content
- index.php
- kirby
- media
- README.md
- site
- src
Build configuration
Also in the projects's root, we create a package.json
file which controls the build process. This file contains two scripts, one for development (watch) and one for live mode (build).
{
"name": "projectname",
"scripts": {
"watch": "npx @tailwindcss/cli -i ./src/tailwind.css -o ./assets/css/styles.css -w",
"build": "npx @tailwindcss/cli -i ./src/tailwind.css -o ./assets/css/styles.css -m"
}
}
Explanation
Use watch
to observe changes and generate a CSS file on change
Use build
to generate a final minified CSS file
-i ./src/tailwind.css
: input file with Tailwind's configuration-o ./assets/css/styles.css
: output file which will be generated-w
: defines watch mode-m
: minify output file
Tailwind configuration
After creating the build configuration, we create a file called tailwind.css
in the /src
folder. This file is used to configure and customize Tailwind CSS.
@import "tailwindcss";
Our /src
folder should look like follows and we are ready to install Tailwind CSS.
src
- tailwind.css
Optional configuration
The above tailwind.css
file is everything that is needed to run Tailwind CSS, but you can adjust it to your needs. As an example:
/* Import a CSS file, which will be included in the final output file */
@import "./font-roboto.css";
@import "tailwindcss";
/* Exclude the 'vendor' directory from beeing scanned */
@source "../vendor";
/* Adjusting variables and adding custom styles */
@theme {
--font-sans: "Roboto", "sans-serif";
--color-primary: rgb(238, 208, 99);
/* ... */
}
More details on how to customize Tailwind CSS can be found on the in the Tailwind CSS docs.
Install Tailwind CSS
Open the terminal window again (and leave it open), change to the project folder and type the following command:
npm install tailwindcss @tailwindcss/cli
By executing the command above a node_modules
folder with the required dependencies and the file package-lock.json
will be automatically created in the project root.
Build
Now we have a fully functional basic setup and are ready to generate our CSS file. Make sure you are in the project root folder and start the watch
or the build
script as follows:
Use watch
to observe changes and generate a CSS file on every change:
npm run watch
Use build
to generate a final minified CSS file:
npm run build
Both scripts scan all files for Tailwind CSS classes and write them to the styles.css
CSS file.
If it doesn't exist, the /assets/
folder structure will be created by the script automatically.
All that's left to do is link to this file in your HTML head
tag:
<?= css('assets/css/styles.css') ?>
Limitations
Writer or other output generating fields won’t work well with this solution so far. As TailwindCSS expects all HTML to have styling classes, the output of these Kirby fields will be completely unstyled (not bold/italic, etc). With the use of the official Tailwind CSS Typography plugin there is a easy way to set the required classes for the Kirby fields and output them to the template.
The official Tailwind CSS Typography plugin provides a set of prose classes you can use to add beautiful typographic defaults to any vanilla HTML you don’t control, like HTML rendered from Markdown, or pulled from a CMS.
Workarounds without the Tailwind CSS Typography plugin
One way to work around this would be to have a separate stylesheet for these cases that define all the output cases again, this time not in Tailwind style but classic CSS:
b, strong {
font-weight: bold;
}
Another solution would be to create your own additional rendering of the fields. This has the advantage that you can use TailwindCSS and nothing else for the page styling but the disadvantage of creating your own output renderer. You need to inject the classes via Regular Expressions that match the allowed HTML tags, for example by using KirbyText hooks like kirbytext:after
.