# Adding Django Tailwind to an Existing Project

This guide explains how to integrate Django Tailwind into a project that already has Django apps, how to make Tailwind CSS scan templates across multiple apps, and how the built-in theme app serves as a centralized entry point for all your styles.

## Overview

Django Tailwind creates a dedicated **theme app** (named `theme` by default) that acts as the single, centralized home for your Tailwind CSS configuration and source styles. Your existing Django apps don't need to be modified structurally — you only need to:

1. Install and configure Django Tailwind.
2. Create the theme app (a one-time step).
3. Add the `{% tailwind_css %}` tag to your base template.
4. Tell Tailwind CSS where your existing templates live (the source-scanning configuration).

Follow the standard [Installation](installation.md) steps, then read the sections below for guidance specific to existing projects.

## Using a Single Theme App Across Multiple Django Apps

By default, the theme app generated by `python manage.py tailwind init` already acts as a **global entry point** for Tailwind CSS. You do **not** need a separate Tailwind setup for each of your Django apps. One theme app is enough for the entire project.

The generated `styles.css` file inside the theme app contains an `@source` directive that tells Tailwind CSS which files to scan for class names. The default configuration is intentionally broad so it covers every app in a standard Django project layout without further changes.

The generated `theme/static_src/src/styles.css` file uses `@source` to point at the whole project:

```css
@import "tailwindcss";

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

The path `../../../**/*.{html,py,js}` resolves to the Django project root (three directories above `styles.css`) and matches all HTML, Python, and JavaScript files found anywhere below it — including every app's `templates/` directory.

## Adjusting Source Paths for Non-standard Project Layouts

If your project does not follow the standard layout — for example, when Django apps are nested inside a subdirectory such as `apps/` or `src/` — the default paths may not match all of your templates. In that case you should widen or redirect the paths.

### Example: apps in a subdirectory

Suppose your project looks like this:

```
myproject/
├── manage.py
├── myproject/
│   └── settings.py
├── apps/
│   ├── blog/
│   │   └── templates/
│   └── shop/
│       └── templates/
└── theme/
    └── static_src/
        └── src/
            └── styles.css
```

The default `@source` path (`../../../**/*.{html,py,js}`) starts from the project root and already covers `apps/blog/templates/` and `apps/shop/templates/`. You only need to change the path if Tailwind CSS is not picking up changes from those directories.

To confirm which files are being detected, run:

```bash
python manage.py tailwind build
```

and check whether the classes from your app templates appear in the generated CSS.

If you need to be more explicit, you can list several `@source` directives:

```css
@import "tailwindcss";

/* Theme app templates */
@source "../../templates/**/*.html";
/* All other app templates */
@source "../../../apps/**/*.html";
/* Python files (class names rendered dynamically) */
@source "../../../apps/**/*.py";
```

## Using the Theme App as a Centralized Style Entry Point

The theme app's `styles.css` is the **single entry point** for all Tailwind CSS customization across the project. You do not need to create per-app CSS files. Instead, add all custom styles, component definitions, and theme extensions to the theme app:

```css
/* 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 compiled CSS is written to `theme/static/css/dist/styles.css` and served through the `{% tailwind_css %}` template tag, which you include once in your base template:

```html
{% load tailwind_tags %}
<!DOCTYPE html>
<html>
<head>
    {% tailwind_css %}
</head>
<body>
    {% block content %}{% endblock %}
</body>
</html>
```

Every app whose templates extend this base template will automatically receive the compiled Tailwind CSS.

## Adding the CSS Tag to an Existing Base Template

If your project already has a `base.html` template (in any app), you can load the Tailwind CSS tag there directly — you do not need to use the `base.html` provided by the theme app:

```html
{% load static tailwind_tags %}
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    ...
    {% tailwind_css %}
    ...
</head>
<body>
    {% block content %}{% endblock %}
</body>
</html>
```

The theme app still handles building and watching the CSS; the tag just tells Django where to load the compiled stylesheet from.

## Summary

| Task | What to do |
|---|---|
| Add Tailwind to an existing project | Follow the standard [Installation](installation.md) steps; create one theme app, leave other apps untouched |
| Cover templates in all apps | Default `@source` paths already scan the whole project; adjust only if your layout is non-standard |
| Centralize all styles | Write custom CSS in `theme/static_src/src/styles.css`; compiled output is shared automatically |
| Use your own base template | Add `{% load tailwind_tags %}` and `{% tailwind_css %}` to your existing `base.html` |