https://github.com/django-commons/django-tailwind-cli
Django and Tailwind integration based on the prebuilt Tailwind CSS CLI.
https://github.com/django-commons/django-tailwind-cli
django django-application python tailwind tailwind-css tailwindcss
Last synced: about 1 month ago
JSON representation
Django and Tailwind integration based on the prebuilt Tailwind CSS CLI.
- Host: GitHub
- URL: https://github.com/django-commons/django-tailwind-cli
- Owner: django-commons
- License: mit
- Created: 2022-10-23T16:09:40.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-05-10T19:26:44.000Z (about 1 month ago)
- Last Synced: 2026-05-10T21:25:33.266Z (about 1 month ago)
- Topics: django, django-application, python, tailwind, tailwind-css, tailwindcss
- Language: Python
- Homepage: https://django-tailwind-cli.rtfd.io/
- Size: 1.64 MB
- Stars: 203
- Watchers: 3
- Forks: 24
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# django-tailwind-cli
**The simplest way to integrate Tailwind CSS with Django** ⚡
No Node.js required! This library provides seamless [Tailwind CSS](https://tailwindcss.com) integration for Django using the standalone [Tailwind CSS CLI](https://tailwindcss.com/blog/standalone-cli). Inspired by the [Tailwind integration for Phoenix](https://github.com/phoenixframework/tailwind), it eliminates the need for Node.js in your Django development workflow.
## ✨ Why django-tailwind-cli?
- **🚀 Zero Node.js dependency** - No npm, webpack, or build tools required
- **⚡ Instant setup** - Get Tailwind running in under 5 minutes
- **🔄 Hot reload** - Watch mode with automatic CSS rebuilding
- **📦 Production ready** - Optimized builds with automatic purging
- **🎨 DaisyUI support** - Built-in component library integration
- **🛠️ Developer friendly** - Rich CLI with helpful error messages and debugging tools
## 🚀 Quick Start
### 1. Install the package
```bash
# Using pip
pip install django-tailwind-cli
# Using uv (recommended)
uv add django-tailwind-cli
# Using poetry
poetry add django-tailwind-cli
```
### 2. Configure Django settings
Add to your `settings.py`:
```python
INSTALLED_APPS = [
# ... your other apps
"django_tailwind_cli",
]
# Configure static files directory — make sure it exists on disk,
# Django raises an error at startup if it does not.
STATICFILES_DIRS = [BASE_DIR / "assets"]
```
```bash
mkdir -p assets
```
### 3. Set up your base template
Create or update your base template (e.g., `templates/base.html`):
```html
{% load tailwind_cli %}
My Django App
{% tailwind_css %}
{% block content %}{% endblock %}
```
### 4. Start developing
```bash
# Start Django's dev server with a parallel Tailwind watcher (recommended)
python manage.py tailwind runserver
# Or run build and watch separately
python manage.py tailwind watch # In one terminal
python manage.py runserver # In another terminal
```
The watcher runs under Django's own auto-reloader, so editing `settings.py` (e.g. adding a new app) restarts it automatically and picks up the new configuration on the fly. Pass `--noreload` to opt out.
First run creates a managed `/.django_tailwind_cli/` directory for the CLI binary and an auto-generated `source.css`. The directory is automatically git-ignored — no entry in your project-level `.gitignore` needed.
> **Tip:** Prefer a guided walkthrough? Run `python manage.py tailwind setup` instead for an interactive step-by-step first-time setup.
### 🎉 You're ready to go!
Start adding Tailwind classes to your templates:
```html
{% extends "base.html" %}
{% block content %}
Welcome to Django + Tailwind!
This text is styled with Tailwind CSS.
Click me!
{% endblock %}
```
📚 **Next Steps:** Check out the [full documentation](https://django-tailwind-cli.rtfd.io/) for advanced configuration and usage patterns.
## 🎯 Core Features
### 🏗️ Build System
- **Automatic CLI download** - No manual setup required
- **Smart caching** - Faster rebuilds with file change detection
- **Production optimization** - Automatic CSS purging and minification
- **Force rebuild** - `--force` flag for clean builds
### 🔧 Development Tools
- **Interactive setup** - `python manage.py tailwind setup`
- **Configuration viewer** - `python manage.py tailwind config`
- **Troubleshooting guide** - `python manage.py tailwind troubleshoot`
### 🎨 Styling Features
- **Tailwind CSS 4.x** - Latest features and performance improvements
- **DaisyUI integration** - Pre-built components via [tailwindcss-cli-extra](https://github.com/dobicinaitis/tailwind-cli-extra)
- **Custom CSS support** - Bring your own styles and configurations
- **Template tag** - Simple `{% tailwind_css %}` inclusion
### ⚡ Performance
- **File change detection** - Only rebuild when necessary
- **Concurrent processing** - Parallel build and server processes
- **Progress indicators** - Visual feedback during downloads and builds
- **Verbose logging** - Detailed diagnostics with `--verbose`
### 🛠️ Management Commands
| Command | Purpose | Example |
| -------------- | ---------------------------------------------------- | ---------------------------------------- |
| `setup` | Interactive first-time setup guide | `python manage.py tailwind setup` |
| `build` | Production CSS build | `python manage.py tailwind build` |
| `watch` | Development file watcher (Django autoreload by default) | `python manage.py tailwind watch` |
| `runserver` | Django dev server + watcher (forwards any runserver flag) | `python manage.py tailwind runserver` |
| `config` | Show current configuration | `python manage.py tailwind config` |
| `troubleshoot` | Debug common issues | `python manage.py tailwind troubleshoot` |
`tailwind runserver` is a transparent passthrough: every positional argument and option (apart from `--force-default-runserver`) is forwarded verbatim to the underlying `runserver` or `runserver_plus`. Every flag those commands accept works — including `runserver_plus`-only ones like `--extra-file`, `--reloader-interval`, and `--print-sql`.
## 📋 Requirements
- **Python:** 3.10+
- **Django:** 4.2 LTS, 5.2, or 6.0
- **Platform:** Windows, macOS, Linux (automatic platform detection)
## ⚙️ Configuration Examples
### Basic Configuration
```python
# settings.py
STATICFILES_DIRS = [BASE_DIR / "assets"]
```
### Advanced Configuration
```python
# Pin specific Tailwind version
TAILWIND_CLI_VERSION = "4.1.3"
# Custom CSS paths
TAILWIND_CLI_SRC_CSS = "src/styles/main.css"
TAILWIND_CLI_DIST_CSS = "css/app.css"
# Enable DaisyUI
TAILWIND_CLI_USE_DAISY_UI = True
# Use an already-installed Tailwind binary (e.g. `brew install tailwindcss`)
TAILWIND_CLI_USE_SYSTEM_BINARY = True
# Auto-inject @source directives for editable-installed external apps (opt-in)
TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS = True
```
### Production Settings
```python
# Optimized for production
TAILWIND_CLI_VERSION = "4.1.3" # Pin version
TAILWIND_CLI_AUTOMATIC_DOWNLOAD = False # Use pre-installed CLI
TAILWIND_CLI_DIST_CSS = "css/tailwind.min.css"
```
## 🔍 Troubleshooting
### Common Issues
**CSS not updating?**
```bash
python manage.py tailwind build --force
python manage.py tailwind troubleshoot
```
**Configuration problems?**
```bash
python manage.py tailwind config
python manage.py tailwind setup
```
**Missing templates?**
Make sure every template directory is covered by an `@source` directive in your
Tailwind CSS input file — Tailwind CSS 4.x discovers templates exclusively
through those directives.
### Performance Tips
1. **Use file watching:** `python manage.py tailwind runserver` for automatic rebuilds
2. **Declare template sources explicitly:** Use `@source` directives in your CSS so Tailwind only scans what you need
3. **Optimize builds:** Use `--force` only when necessary
4. **Monitor file changes:** Use `--verbose` for detailed logging
## 🎨 DaisyUI Integration
Enable beautiful pre-built components:
```python
# settings.py
TAILWIND_CLI_USE_DAISY_UI = True
```
```html
Primary Button
Card Title
Card content goes here.
```
## 📚 Documentation & Resources
- **📖 Full Documentation:** [django-tailwind-cli.rtfd.io](https://django-tailwind-cli.rtfd.io/)
- **🎯 Tailwind CSS Docs:** [tailwindcss.com](https://tailwindcss.com)
- **🧩 DaisyUI Components:** [daisyui.com](https://daisyui.com)
- **💬 Django Commons:** [github.com/django-commons](https://github.com/django-commons)
## 🔗 Related Projects
- **tailwindcss-cli-extra:** [DaisyUI-enabled CLI](https://github.com/dobicinaitis/tailwind-cli-extra)
- **Django Extensions:** [Extended runserver features](https://django-extensions.readthedocs.io/)
- **Tailwind CSS IntelliSense:** [VS Code extension](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
## 🤝 Contributing
We welcome contributions! This project uses modern Python tooling for development.
### Prerequisites
- **[uv](https://docs.astral.sh/uv/)** - Fast Python package manager
- **[just](https://github.com/casey/just)** - Command runner (optional but recommended)
### Quick Development Setup
```bash
# Clone the repository
git clone https://github.com/django-commons/django-tailwind-cli.git
cd django-tailwind-cli
# Setup development environment (with just)
just bootstrap
# Or setup manually with uv
uv venv
uv sync --all-extras
```
### Development Commands
```bash
# With just (recommended)
just upgrade # Update dependencies
just lint # Run linting and formatting
just test # Run test suite
just test-all # Run tests across Python/Django versions
# Without just
uv sync --all-extras # Update dependencies
uvx pre-commit run --all-files # Run linting
uv run pytest # Run tests
uvx --with tox-uv tox # Run full test matrix
```
### Contribution Guidelines
1. **🍴 Fork** the repository
2. **🌿 Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **✅ Test** your changes (`just test`)
4. **📝 Commit** with conventional commits (`feat:`, `fix:`, `docs:`, etc.)
5. **📤 Push** to your branch (`git push origin feature/amazing-feature`)
6. **🔄 Create** a Pull Request
### Code Quality
- **Type hints** for all new code
- **Tests** for new features and bug fixes
- **Documentation** updates for user-facing changes
- **Conventional commits** for clear history
## License
This software is licensed under [MIT license](https://github.com/django-commons/django-tailwind-cli/blob/main/LICENSE).