django-tailwind

django-tailwind is a Django app that wires Tailwind CSS into a Django project the way Django itself expects things to work: python manage.py tailwind init scaffolds a dedicated theme app containing the Tailwind source, config, and templates, then install, build, start, and dev subcommands handle dependency installation, production builds, file-watching, and running the Django dev server and Tailwind watcher together via Honcho.

It supports two installation modes — a standalone Tailwind CLI binary (no Node.js needed at all) or a conventional npm-based pipeline for teams that already have a Node toolchain and want access to the broader PostCSS/npm plugin ecosystem. A {% tailwind_css %} template tag handles linking the compiled stylesheet, with automatic cache-busting and hot-reload support during development.

What You Get

• A manage.py tailwind init scaffolder that generates a complete Tailwind app (config, source CSS, templates) inside your Django project
• Choice of a standalone Tailwind CLI binary (zero Node.js dependency) or a full npm-based build for access to the wider plugin ecosystem
• Combined dev workflow: manage.py tailwind dev runs the Django server and the Tailwind watcher together via Honcho, with live CSS/template reload
• A {% tailwind_css %} template tag for including the compiled stylesheet, with dev-mode cache-busting built in
• A plugin_install management command that installs and wires up npm-based Tailwind plugins automatically
• Optional DaisyUI component library integration selectable at init time

Common Use Cases

• Adding Tailwind CSS to a fresh or existing Django project without hand-rolling a Node.js build pipeline
• Running Tailwind’s build/watch process alongside runserver during local development with one command
• Deploying Tailwind CSS in production Django environments where installing Node.js is undesirable, via the standalone binary mode
• Migrating a Django project between Tailwind v3 and v4 using the package’s version-specific app templates

Under The Hood

Architecture The package centers on a single Django BaseCommand subclass (tailwind.py) that registers argparse subparsers for init, install, build, start, dev, check-updates, update, and plugin_install, each dispatching to its own handler method. Every subcommand except init first runs through a Validations class (validate.py) that checks TAILWIND_APP_NAME is set, the target app is registered in INSTALLED_APPS, and it looks like a real Tailwind app before proceeding. Depending on whether a package.json exists (or TAILWIND_USE_STANDALONE_BINARY is set), commands branch between an NPM wrapper (npm.py) that shells out to npm via subprocess, and the standalone pytailwindcss binary. App scaffolding for init renders one of three Cookiecutter templates (app_template_v3, app_template_v4, app_template_v4_standalone) into the target app directory. It’s a straightforward command-dispatch structure with no dependency injection or service layering — each handler is largely self-contained, so the surface most likely to break under change is the Validations + config-resolution path shared by every non-init subcommand.

Tech Stack Python 3.11+ targeting Django 4.2.20 through the 6.0 pre-release, built with hatchling. Core runtime dependencies are just django and pytailwindcss (the standalone Tailwind CLI wrapper); optional extras add cookiecutter for app scaffolding, honcho for running the combined dev process group, and django-browser-reload for template/CSS hot reload. Tooling is uv-managed, with ruff (bugbear, comprehensions, Django-specific, isort, simplify, pyupgrade rulesets) for linting, pre-commit for enforcement, pytest + pytest-django for tests across a tox matrix, and Sphinx/MyST for the hosted documentation site.

Code Quality Tests live under tests/ (test_cli.py, test_dev_command.py, test_templatetags.py, test_utils.py) using pytest with parametrized cases and given/when/then-style docstrings, run via pytest-django against a real settings module. CI runs a pre-commit (ruff) gate before a matrix of Python 3.11–3.14 test runs. Errors are handled through dedicated ValidationError and NPMException types surfaced as readable CLI messages rather than raw tracebacks. There’s no static type-checking (no mypy/pyright in the toolchain), but linting is thorough and consistently enforced.

API Design The public surface is intentionally thin: a handful of manage.py tailwind <subcommand> commands plus two template tags ({% tailwind_css %}, {% tailwind_preload_css %}). The standalone-binary mode is the package’s clearest differentiator — most Django-plus-frontend-tooling integrations assume Node.js is available, while this one lets a project ship Tailwind CSS with zero JavaScript runtime dependency. That’s a genuinely useful, if not deeply novel, design decision that meaningfully lowers onboarding friction for Django developers unfamiliar with frontend build tooling.