fasthtml-tailwindcss — Tailwind CSS for FastHTML with persistent watch mode

[SpaceShaman]

Hi everyone! I’d like to share fasthtml-tailwindcss, a small library for using Tailwind CSS in FastHTML, with automatic CSS rebuilds and a compiler that stays alive across server reloads.

Installation

Using uv:

uv add fasthtml-tailwindcss

Or pip:

pip install fasthtml-tailwindcss

On Alpine Linux, install the system runtime with apk add --no-cache libstdc++ libgcc.

Usage

from fasthtml.common import Div, FastHTML
from fasthtml_tailwindcss import TailwindHead

app = FastHTML(hdrs=[TailwindHead(watch=True)])


@app.route("/")
def get():
    return Div("Hello", cls="rounded-lg bg-blue-500 p-4 text-white")

Run your application as usual:

uv run uvicorn main:app --reload

The package bundles the official standalone Tailwind compiler for your platform, so you don’t need Node.js, npm, a CDN, or a separate Tailwind command. Generated CSS is embedded directly in the page’s <head>.

Watch mode and server reloads

With watch=True, Tailwind watches your source files and rebuilds CSS as classes change. The compiler keeps running across Uvicorn reloads, so restarting the application process doesn’t start another watcher or trigger another initial build.

Each full page receives the latest completed CSS. Refresh the browser to see changes; browser live reload and updating styles during HTMX fragment swaps aren’t included.

With watch=False, CSS is built once with minification and reused across server reloads during the same session.

Customization

You can pass source paths, extra CSS, or a custom input stylesheet directly to TailwindHead:

TailwindHead(
    watch=True,
    sources=["app"],
    css="@theme { --color-brand: #7854f7; }",
)

TailwindHead(watch=True, input="assets/app.css")

Automatic updates

A daily GitHub Actions workflow checks for new stable Tailwind releases, builds and tests the platform wheels, and publishes updates to PyPI.

The PyPI version matches the bundled Tailwind release. Python-only fixes use a .postN suffix while keeping the same Tailwind compiler.

Links

• GitHub repository
• PyPI package

Feedback and suggestions are welcome!