Skip to content

Kirby meets Tailwind CSS

This is a walkthrough on how to install and use Tailwind CSS 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

Configuration

Also in the projects's root, we create a package.json file which controls the build process. This file contains two build scripts, one for development (watch) and one for live mode (build).

/package.json
{
    "name": "projectname",
    "scripts": {
        "watch": "npx tailwindcss -i ./src/css/tailwind.css -o ./assets/css/styles.css --jit --purge './site/**/*.php' -w",
        "build": "npx tailwindcss -i ./src/css/tailwind.css -o ./assets/css/styles.css --jit --purge './site/**/*.php' -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/css/tailwind.css: input file with Tailwind's css classes
  • -o ../assets/css/styles.css: output file which will be generated
  • --jit: Tailwinds just in time engine (still preview, but highly recommend!)
  • --purge '../site/**/*.php': folder to watch for Tailwind's classes
  • -w: defines watch mode
  • -m: minify output file

CSS Styles

After creating the build configuration, we create a subfolder /css in the /src folder and inside that folder a file called tailwind.css. Inside that file we use the @tailwind directive to inject Tailwind’s base, components, and utilities styles.

/src/css/tailwind.css
@tailwind base;
@tailwind components;
@tailwind utilities;

Our /src folder should look like follows and we are ready to install Tailwind CSS.

  • src
    • css
    • tailwind.css

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@latest

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.

Config Tailwind CSS (optional)

If you want to customize your Tailwind installation, you can create an additional config file tailwind.config.js in the project root. This file will then be automatically processed at build time if it exists.

/tailwind.config.js
module.exports = {
  darkMode: false,
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

More details on how to customize Tailwind CSS can be found on the in the Tailwind CSS docs.

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 php files inside the /site folder for Tailwind CSS classes and write them to the CSS file styles.css.

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') ?>

Author