fasthtml-tailwindcss

Tailwind CSS for FastHTML with a persistent development watcher and a build command for production CSS.

Installation

The dev extra installs the standalone compiler through fasthtml-tailwindcss-cli. No Node.js or npm is needed. Production only needs the wrapper and generated CSS.

On Alpine Linux, the compiler also needs:

apk add --no-cache libstdc++ libgcc

Usage

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

app = FastHTML(hdrs=[TailwindHead(watch=True)])
app.mount("/static", StaticImmutable(directory="static"), name="static")


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

TailwindHead creates the output directory and adds a stylesheet link. vurl versions the URL by content, and StaticImmutable lets browsers cache the CSS until it changes.

Watch mode

uv run uvicorn main:app --reload

For app/main.py, run uv run --directory app uvicorn main:app --reload from the project directory.

With watch=True, compilation starts on the first page render and CSS rebuilds when sources change. The watcher survives server reloads, restarts if settings change, and stops 15 seconds after the last application stops using it. Refresh the browser to see changes; automatic browser refresh and stylesheet updates during HTMX fragment swaps are not included.

Production

Use TailwindHead() with the default watch=False in the application, then build CSS in your deployment pipeline with the dev extra installed:

uv run fasthtml-tailwindcss build main:app

The command imports the app and builds minified CSS using its TailwindHead settings. The app must have exactly one TailwindHead in hdrs. For app/main.py, run build app.main:app from the project directory or build main:app from app/; both write to app/static/tailwind.css by default.

Deploy the generated CSS alongside the application. With watch=False, TailwindHead only links the stylesheet; it does not run the compiler.

Options

All configuration is passed to TailwindHead:

TailwindHead(
    watch=True,
    css="@theme { --color-brand: #7854f7; }",
    output="static/app.css",
)

• watch: enable the persistent development compiler. Defaults to False.
• sources: files or directories to scan. Defaults to the working directory; with a custom input, its own source detection applies unless extra sources are supplied.
• input: custom stylesheet, such as input="assets/app.css", replacing the built-in @import "tailwindcss". Relative CSS imports resolve from that file.
• css: CSS appended after the input, useful for @theme, variants, and @source inline(...).
• output: CSS file path, defaulting to ./static/tailwind.css. The stylesheet URL follows this path, so mount its directory at the corresponding URL.

Paths are relative to the working directory. The build command uses the application module's directory; run the server from that directory too. Temporary files and compiler logs live in .fasthtml-tailwindcss/, which you can add to .gitignore.

Use complete class names such as "bg-red-500"; Tailwind cannot detect names constructed with f"bg-{color}-500". Classes in installed component libraries need explicit sources or safelisting.

For inline Lucide SVG icons with typed names and editor autocomplete, see fasthtml-lucide.

Development

Setup and tests

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

Build

uv build --no-sources
uv build packages/cli --no-sources

CLI wheel builds download and verify the official executable using SHA-256. Supported platforms are Linux x64/ARM64 (glibc 2.28+ or musl 1.2+), macOS 13+ (Intel/Apple Silicon), and Windows x64. Building a CLI wheel needs network access unless the verified binary is already available locally.

Automated releases

GitHub Actions checks daily for a new stable Tailwind CSS release, then builds and tests both packages before publishing them to PyPI. Both package versions track the Tailwind version; wrapper-only fixes may add a .postN suffix.

The Release workflow builds and tests both packages before publishing through PyPI Trusted Publishing. Configure the same publisher (SpaceShaman/fasthtml-tailwindcss, workflow release.yml, environment pypi) for both PyPI projects, and allow workflow version commits on the default branch.

Links

• GitHub repository
• PyPI package
• Tailwind CLI package

License

The wrapper and Tailwind CSS are MIT licensed. The CLI package includes both license notices.