django-tailwind

Tailwind CSS needs to know which files to scan for class names. By default, the generated theme/static_src/src/styles.css uses an @source directive that points to the project root, covering all HTML, Python, and JavaScript files.

If your project uses a non-standard layout (e.g., apps are nested in an apps/ or src/ directory) and the default scanning isn't working, you can explicitly define @source paths in theme/static_src/src/styles.css.

To verify if your templates are being detected, run:

python manage.py tailwind build

Then check if the classes from your app templates appear in the generated CSS output.

When running python manage.py tailwind plugin_install <plugin-name>, the following lifecycle occurs:

1. NPM Installation: The plugin is added to your theme app's package.json as a development dependency.
2. Styles Configuration: The command inserts the plugin directive into your styles.css file, specifically placing it immediately after the @import "tailwindcss"; line.
3. Duplicate Prevention: The command checks if the plugin is already installed to prevent redundant entries.

Example styles.css transformation (after installing DaisyUI):

Before:

@import "tailwindcss";
@source "../../**/*.{html,py,js}";

/* Your custom styles here */

After:

@import "tailwindcss";
@plugin "daisyui";
@source "../../**/*.{html,py,js}";

/* Your custom styles here */

To avoid confusion when reading the documentation, note the following distinctions:

• Django Tailwind: Refers specifically to this Django package used to integrate Tailwind CSS into your Django project.
• Tailwind CSS: Refers to the standalone CSS framework.

This distinction is important because configuration and commands may refer to either the Django package or the underlying CSS framework.

The theme/static_src/src/styles.css file is the single entry point for all project-wide Tailwind customization. Instead of creating per-app CSS files, add all custom styles, design tokens, and reusable component classes here using @layer directives.

Example of centralized styling:

/* theme/static_src/src/styles.css */
@import "tailwindcss";

@source "../../../**/*.{html,py,js}";

/* Custom CSS variables / design tokens */
@layer base {
    :root {
        --color-brand: oklch(55% 0.2 250);
    }
}

/* Reusable component classes used across apps */
@layer components {
    .btn-primary {
        @apply bg-blue-600 text-white px-4 py-2 rounded hover:bg-blue-700;
    }
}

The development experience relies on two main mechanisms:

1. CSS Compilation: Every time you add or remove a Tailwind CSS class in a Django template, the stylesheet is updated.
   • npm-based installations use npm scripts and PostCSS to watch and compile.
   • Standalone installations use the Tailwind CSS standalone binary to watch files.
2. Automatic Browser Reloading: The system uses django-browser-reload to watch for changes in HTML and CSS files. When a template or CSS file is updated, the browser refreshes automatically.

You can start your development environment using two different approaches:

• Option 1 (Recommended): Use python manage.py tailwind dev to start both the Django server and the Tailwind watcher simultaneously using honcho.
• Option 2: Use python manage.py tailwind start to run only the Tailwind watcher. You will need to run python manage.py runserver in a separate terminal.

To run the provided example project for local development, follow these steps:

1. Install the necessary Python dependencies using pip from the requirements.txt file.
2. Start the Django development server using manage.py runserver.
3. Access the application by navigating to http://localhost:8000 in your web browser.

To add Tailwind CSS to a project that already has existing Django apps, follow these steps:

1. Install and configure django-tailwind following the standard installation guide.
2. Create the theme app once using python manage.py tailwind init (this creates a dedicated app, usually named theme).
3. Add the CSS tag to your existing base template using {% tailwind_css %}.
4. Configure source scanning to ensure Tailwind detects classes in your existing app templates.

You do not need to modify your existing apps structurally; the theme app acts as a centralized hub for all styles.

After installation, follow these steps to integrate the package into your Django project:

1. Add 'tailwind' to your INSTALLED_APPS in settings.py.
2. Initialize your Tailwind theme app (e.g., named theme) using python manage.py tailwind init. You will be prompted to choose between a standalone binary or npm-based installation.
3. Add your new theme app (e.g., 'theme') to INSTALLED_APPS.
4. Register the theme app by setting the TAILWIND_APP_NAME variable in settings.py to the name of your theme app.

# settings.py

INSTALLED_APPS = [
    "tailwind",
    "theme",  # Replace 'theme' with your actual app name
]

TAILWIND_APP_NAME = "theme"

To use Tailwind CSS in your HTML templates, you must load the tailwind_tags and use the {% tailwind_css %} tag within the <head> section. This tag injects the necessary stylesheet.

{% load static tailwind_tags %}

<head>
    ...
    {% tailwind_css %}
    ...
</head>

If your project was initialized with the --tailwind-version 4s flag, you are using the standalone binary mode. To update the version, you must manually update your Django settings and then trigger a re-installation and build.

1. Find the desired version on the Tailwind CSS releases page.
2. Update the TAILWIND_STANDALONE_BINARY_VERSION setting in your settings.py.
3. Run python manage.py tailwind install to download the new binary.
4. Run python manage.py tailwind build to rebuild your CSS.

Note: The check-updates and update management commands are not available for standalone installations.

# settings.py
TAILWIND_STANDALONE_BINARY_VERSION = "v4.2.0"  # Change to desired version