Development Workflow¶

This guide covers development workflows for django-tailwind-cli.

Initial Setup¶

# Step 1: Install and configure
pip install django-tailwind-cli
python manage.py tailwind setup  # Interactive setup

# Step 2: Verify configuration
python manage.py tailwind config

# Step 3: Start development
python manage.py tailwind runserver

Daily Development¶

# Morning startup
python manage.py tailwind runserver  # Starts both Django and Tailwind

# Alternative: Separate terminals
python manage.py tailwind watch     # Terminal 1: CSS watching
python manage.py runserver          # Terminal 2: Django server

tailwind watch (and the inner watcher spawned by tailwind runserver) runs under Django’s auto-reloader by default. Any change to a Python file — including settings.py — restarts the watcher, regenerates the source CSS file, and respawns the Tailwind CLI subprocess. Pass --noreload to disable.

tailwind runserver is a transparent wrapper around the underlying Django runserver / runserver_plus command: every runserver flag is forwarded verbatim. Consult python manage.py runserver --help (or runserver_plus --help with django-extensions installed) for the full list of available options.

Template Development¶

Create/Edit Template

<!-- templates/myapp/page.html -->
{% extends "base.html" %}

{% block content %}
<div class="max-w-4xl mx-auto p-6">
  <h1 class="text-3xl font-bold text-gray-900">New Page</h1>
</div>
{% endblock %}

Declare template sources

Make sure your Tailwind CSS input file contains @source directives for the template directories you want scanned. Tailwind CSS 4.x relies on these directives exclusively — there is no external template-listing command.

Build and Test

# CSS rebuilds automatically with watch mode
# Or manually: python manage.py tailwind build

IDE Integration¶

VS Code Setup¶

Install Extensions:
- Tailwind CSS IntelliSense
- Django Template
- Python

Workspace Settings:

// .vscode/settings.json
{
  "tailwindCSS.includeLanguages": {
    "django-html": "html"
  },
  "tailwindCSS.files.exclude": [
    "**/.git/**",
    "**/node_modules/**"
  ],
  "files.associations": {
    "*.html": "django-html"
  }
}

Tasks Configuration:

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Tailwind Runserver",
      "type": "shell",
      "command": "python",
      "args": ["manage.py", "tailwind", "runserver"],
      "group": "build",
      "isBackground": true
    }
  ]
}

PyCharm Setup¶

Run Configurations:
- Name: Tailwind Watch
- Script: manage.py
- Parameters: tailwind watch
- Environment: Development
File Watchers:
- File type: Django Template
- Scope: Project Files
- Program: python
- Arguments: manage.py tailwind build

Troubleshooting Checklist¶

Before Asking for Help¶

Check Configuration:
```
python manage.py tailwind config
```
Verify Template Sources:

Open your Tailwind CSS input file and confirm that every template directory you expect to be scanned is referenced by an @source directive.

Test CLI Functionality:

python manage.py tailwind download_cli
python manage.py tailwind build --verbose

Run Diagnostics:
```
python manage.py tailwind troubleshoot
```
Check System Requirements:
- Python 3.10+
- Django 4.2+
- Sufficient disk space
- Network access for CLI download

Information to Include in Bug Reports¶

Environment:
- OS: [macOS/Linux/Windows version]
- Python: [version]
- Django: [version]
- django-tailwind-cli: [version]

Configuration:
- STATICFILES_DIRS: [value]
- TAILWIND_CLI_VERSION: [value]
- Custom settings: [list any custom Tailwind settings]

Command Output:
[Paste output from python manage.py tailwind config]

Error Message:
[Full error message and traceback]

Steps to Reproduce:
1. [First step]
2. [Second step]
3. [etc.]