fasthtml-tailwindcss

Tailwind CSS for FastHTML with a persistent compiler across server reloads and watch mode for automatic CSS rebuilds.

Installation

Install with uv:

uv add fasthtml-tailwindcss

Or with pip:

pip install fasthtml-tailwindcss

On Alpine Linux, the standalone compiler also requires the system C++ runtime:

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 normally, for example with uv run uvicorn main:app --reload. The package bundles the official standalone Tailwind compiler: no Node.js, npm, CDN, CSS endpoint or additional command is needed.

TailwindHead builds CSS when the component is constructed, usually while importing your application module, and waits for the first successful compilation. It embeds the result in a <style> element. Each full page receives the latest completed CSS. Refresh the browser to see updates; automatic browser refresh and updating styles during HTMX fragment swaps are not included.

• watch=True: compile once, then watch source files. The compiler survives application reloads.
• watch=False (default): compile once with minification, then reuse the result across reloads. Source changes do not rebuild CSS during that session.

A local helper keeps the session alive while applications renew a shared heartbeat file, and shuts down 15 seconds after the last heartbeat. A quick manual restart is treated like a reload. A later start creates a fresh session and builds again. The session stays active while the component exists in a running Python process; it does not depend on ASGI lifespan.

Options

All configuration is passed to TailwindHead:

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

For a custom input stylesheet:

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

• sources: source files or directories. Defaults to the project directory with the built-in input; with a custom input, its own source detection is used unless extra sources are supplied.
• input: optional stylesheet replacing the built-in @import "tailwindcss". Relative CSS imports resolve from that file.
• css: optional inline CSS appended after the input. Useful for @theme, variants and explicit @source inline(...) declarations.

Paths are resolved relative to the nearest pyproject.toml above the working directory, or the working directory if none exists. Sessions are shared by project, configuration and OS user. Reloads and application workers with identical options reuse the same session. Changing options, including watch, starts a separate session immediately; the unused session shuts down after 15 seconds.

Tailwind scans complete class names in source files. Use "bg-red-500" rather than constructing names such as f"bg-{color}-500". Classes inside installed component libraries need explicit sources or safelisting.

Generated files and compiler diagnostics (compiler.log) live in the OS user cache under fasthtml-tailwindcss. Nothing is written into your application or installed package. Inline CSS requires an appropriate Content Security Policy if your application sets one.

Development

uv sync --group test
uv run --group test pytest
uv build

Wheel builds download and verify the matching official standalone executable. Wheels target Linux x64/ARM64 (glibc 2.28+ or musl 1.2+), macOS 13+ (Intel/Apple Silicon), and Windows x64. Source distributions contain the build hook and checksum manifest; building one requires network access unless the verified compiler is already present locally.

The package version follows Tailwind, with .postN for Python-only fixes. The release workflow checks upstream daily, tests the platform wheels and publishes through PyPI Trusted Publishing. Configure the publisher for SpaceShaman/fasthtml-tailwindcss, workflow release.yml, environment pypi; allow workflow version commits on the default branch.

Links

• GitHub repository
• PyPI package

License

The wrapper and Tailwind CSS are MIT licensed. Both license notices are included in distributions.