feat(config): auto @source external apps and watch-mode auto-reload

Two related features addressing issue #187, both landed together so they
compose on the first release.

1. Auto @source injection (opt-in):
   New setting TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS (default False).
   When enabled, the auto-generated default source.css gains one
   @source directive per installed Django app whose path lies both
   outside BASE_DIR and outside every known site-packages directory.
   That's the exact shape of the issue #187 pain point: editable
   installs of a sibling source repository whose templates Tailwind
   cannot see on its own. Internal apps are left to Tailwind's CWD
   walk; regular pip-installed third-party apps are filtered out via
   a site.getsitepackages() / sysconfig check so we don't pull in
   django.contrib.admin and friends.

   The directive points at the app base dir, not at a glob, so
   Tailwind's own file walker handles extension detection and
   .gitignore exclusion — and incidentally picks up Tailwind class
   strings embedded in Python code (form widgets, admin Media
   classes, etc.).

2. Watch-mode auto-reload:
   tailwind watch now wraps its loop in
   django.utils.autoreload.run_with_reloader — the same machinery
   manage.py runserver uses. Editing settings.py (e.g. adding a new
   INSTALLED_APPS entry) restarts the watch process, regenerates
   source.css with the fresh external-app list, and respawns the
   Tailwind CLI subprocess. Pass --noreload to disable.

   Tests that exercise watch via call_command now bypass the
   reloader with an autouse fixture that mocks run_with_reloader to
   invoke its callable directly. This keeps the existing test suite
   in-process instead of forking per invocation.

Opt-in on the setting was a deliberate choice: the feature injects
extra directives into a generated file and expands Tailwind's scan
scope. Users who don't need it see no behaviour change, and the one
user who hits the issue flips a single flag.

Author: oliverandrich

CHANGELOG.md

@@ -8,6 +8,8 @@
 ### 🎯 New Features
 - **Configurable minification**: New `TAILWIND_CLI_AUTOMATIC_MINIFY` setting and `--minify` / `--no-minify` flag on `tailwind build` for projects whose asset pipelines already minify CSS. Defaults preserve existing behavior.
 - **System binary support**: New `TAILWIND_CLI_USE_SYSTEM_BINARY` setting lets `django-tailwind-cli` use a Tailwind CSS CLI that is already installed on `PATH` (e.g. via Homebrew), skipping the auto-download. Pairs with optional `TAILWIND_CLI_SYSTEM_BINARY_NAME` override. Emits a warning if the installed binary's version differs from an explicitly pinned `TAILWIND_CLI_VERSION`.
+- **Auto `@source` for editable external apps** (opt-in): New `TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS` setting (default `False`). When enabled, the auto-generated default source CSS receives one `@source` directive per installed Django app whose path lives outside both `BASE_DIR` and site-packages — typically editable-installed packages that ship their own templates. This removes the need for fragile `@source "../../../../../..."` workarounds. Addresses [#187](https://github.com/django-commons/django-tailwind-cli/issues/187).
+- **Watch mode auto-reload**: `python manage.py tailwind watch` now runs under Django's own auto-reloader (the same machinery `runserver` uses). Changing `settings.py` or any Python file restarts the watch process, regenerates the source CSS (picking up new `INSTALLED_APPS`), and restarts the Tailwind CLI subprocess. Pass `--noreload` to disable.
 
 ### 🛠️ Developer Experience
 - **Gitignore cleanup**: Trimmed `.gitignore` to project-relevant entries only

docs/settings.md

@@ -42,6 +42,38 @@ In case you want to use the new behaviour, it is highly recommended to also set
 
 Enable or disable the automatic downloading of the official CLI to your machine.
 
+### TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS
+
+**Default**: `False` (opt-in)
+
+When enabled, the auto-generated default source CSS file gains one `@source` directive per installed Django app whose path lives **outside** `BASE_DIR` **and** outside every known site-packages directory. This covers exactly one real-world case: editable-installed packages that ship with their own templates, e.g. `pip install -e ../my-ui-library`.
+
+Why it matters: Tailwind CSS 4.x discovers source files by walking the current working directory tree. Apps installed as editable packages from a sibling repository sit outside that tree and are therefore invisible to Tailwind unless declared explicitly. Turning this setting on makes `django-tailwind-cli` emit the declarations for you, using absolute paths that Tailwind can follow.
+
+```python
+# settings.py
+TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS = True
+```
+
+With the setting enabled and an editable package `extra` installed, the auto-generated `source.css` looks like:
+
+```css
+@import "tailwindcss";
+
+/* Auto-generated: installed apps outside BASE_DIR and site-packages. */
+@source "/absolute/path/to/editable/extra";
+```
+
+:::{note}
+The directive points at the app base dir, not at a glob. Tailwind CSS 4.x walks the directory and applies its own exclusions (`.gitignore`, binaries, etc.) — this also means class names embedded in Python files (e.g. form widget `attrs={"class": "..."}` strings) are picked up automatically.
+:::
+
+:::{warning}
+This setting only affects the **auto-generated** default source CSS. If you set `TAILWIND_CLI_SRC_CSS` to point at a hand-written CSS file, that file is left untouched — add the `@source` directives yourself if you need them.
+:::
+
+The list of external apps is re-evaluated whenever the source CSS is written. When combined with the `tailwind watch` auto-reloader, installing a new app or editing `INSTALLED_APPS` automatically regenerates the declarations and triggers a Tailwind rebuild.
+
 ### TAILWIND_CLI_USE_SYSTEM_BINARY
 
 **Default**: `False`

docs/usage.md

@@ -22,6 +22,14 @@ Run `python manage.py tailwind build` to create an optimized production built of
 
 Run `python manage.py tailwind watch` to just start a tailwind watcher process if you prefer to start your debug server in a seperate shell or prefer a different solution than runserver or runserver_plus.
 
+By default the watch command runs under Django's own auto-reloader (the same one `runserver` uses). Whenever you change a Python file — including `settings.py` — the watcher restarts its Python process, regenerates the default source CSS file (picking up freshly added `INSTALLED_APPS`), and restarts the Tailwind CLI subprocess. This pairs nicely with [`TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS`](settings.md#tailwind_cli_auto_source_external_apps): adding an editable-installed app and updating `INSTALLED_APPS` is enough — no manual restart needed.
+
+Pass `--noreload` if you want a single-process watch loop (e.g. in CI or when debugging the watcher itself):
+
+```bash
+python manage.py tailwind watch --noreload
+```
+
 ### runserver
 
 Run `python manage.py tailwind runserver` to start the classic Django debug server in parallel to a tailwind watcher process.

src/django_tailwind_cli/config.py

@@ -55,6 +55,19 @@
             Default: True
             Example: TAILWIND_CLI_AUTOMATIC_DOWNLOAD = False
 
+        TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS (optional): Auto @source
+            Default: False (opt-in)
+            Example: TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS = True
+            Note: When enabled AND the default source.css is auto-generated,
+                  scan INSTALLED_APPS for Django apps that live outside both
+                  BASE_DIR and site-packages (typically editable-installed
+                  user packages), and emit an @source directive for each.
+                  This makes Tailwind CSS scan templates of those apps even
+                  though they sit outside its default CWD walk. Opt-in
+                  because it inserts extra directives into the generated
+                  source.css and expands Tailwind's scan scope — users who
+                  don't need it should see no behavior change.
+
         TAILWIND_CLI_USE_SYSTEM_BINARY (optional): Use a CLI on PATH
             Default: False
             Example: TAILWIND_CLI_USE_SYSTEM_BINARY = True
@@ -138,6 +151,7 @@ class Config:
     automatic_download: bool = True
     use_daisy_ui: bool = False
     uses_system_binary: bool = False
+    auto_source_external_apps: bool = False
 
     # Backward compatibility properties
     @property
@@ -697,6 +711,7 @@ def get_config() -> Config:
     use_daisy_ui = getattr(settings, "TAILWIND_CLI_USE_DAISY_UI", False)
     automatic_download = getattr(settings, "TAILWIND_CLI_AUTOMATIC_DOWNLOAD", True)
     uses_system_binary = bool(getattr(settings, "TAILWIND_CLI_USE_SYSTEM_BINARY", False))
+    auto_source_external_apps = bool(getattr(settings, "TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS", False))
 
     # Get platform information
     platform_info = get_platform_info()
@@ -735,6 +750,7 @@ def get_config() -> Config:
         automatic_download=automatic_download,
         use_daisy_ui=use_daisy_ui,
         uses_system_binary=uses_system_binary,
+        auto_source_external_apps=auto_source_external_apps,
     )
 
 

src/django_tailwind_cli/management/commands/tailwind.py

@@ -291,6 +291,11 @@ def watch(
         "-v",
         help="Show detailed watch information and diagnostics.",
     ),
+    no_reloader: bool = typer.Option(
+        False,
+        "--noreload",
+        help="Disable auto-reload on Python file changes.",
+    ),
 ):
     """Start Tailwind CSS in watch mode for development.
 
@@ -307,14 +312,25 @@ def watch(
     - Build progress and timing
     - Any build errors or warnings
 
+    \b
+    By default the Python process that runs the watch mode is itself
+    auto-reloaded on any .py file change (using Django's own autoreload
+    machinery — the same one runserver uses). This means that installing
+    a new Django app or editing settings.py rebuilds the source.css and
+    restarts the Tailwind CLI subprocess automatically. Pass --noreload
+    to disable this and run the watch loop in a single process.
+
     \b
     Examples:
-        # Start watch mode
+        # Start watch mode with auto-reload
         python manage.py tailwind watch
 
         # Watch with detailed diagnostics
         python manage.py tailwind watch --verbose
 
+        # Single-process watch without auto-reload
+        python manage.py tailwind watch --noreload
+
     \b
     Tips:
         - Keep this running in a separate terminal during development
@@ -323,6 +339,25 @@ def watch(
 
     Press Ctrl+C to stop watching.
     """
+    if no_reloader:
+        _run_watch_loop(verbose=verbose)
+        return
+
+    from django.utils import autoreload
+
+    autoreload.run_with_reloader(_run_watch_loop, verbose=verbose)  # pyright: ignore[reportUnknownMemberType]
+
+
+def _run_watch_loop(*, verbose: bool = False) -> None:
+    """Run the Tailwind CSS watch loop in the current process.
+
+    This is invoked directly by ``tailwind watch --noreload`` and as the
+    inner callable when Django's autoreload machinery spawns a child
+    process for the default (auto-reload) path. On reload the entire
+    child process is torn down and respawned, so this function starts
+    from a clean slate every time — including a fresh get_config() call
+    that picks up any INSTALLED_APPS or settings changes.
+    """
     config = get_config()
 
     if verbose:
@@ -1538,6 +1573,88 @@ def _download_cli_with_verbose(*, verbose: bool = False, force_download: bool =
 DAISY_UI_SOURCE_CSS = '@import "tailwindcss";\n@plugin "daisyui";\n'
 
 
+def _get_site_packages_paths() -> list[Path]:
+    """Return all known site-packages paths used to filter out regular installs.
+
+    We combine ``site.getsitepackages()``, ``site.getusersitepackages()`` and
+    ``sysconfig.get_paths()`` to catch every standard location — editable
+    installs of the user's own source packages live outside all of these.
+    """
+    import site
+    import sysconfig
+
+    paths: set[Path] = set()
+    for p in site.getsitepackages():
+        paths.add(Path(p).resolve())
+    try:
+        user_site = site.getusersitepackages()
+        if user_site:
+            paths.add(Path(user_site).resolve())
+    except AttributeError:  # pragma: no cover - defensive
+        pass
+    for key in ("purelib", "platlib"):
+        p = sysconfig.get_paths().get(key)
+        if p:
+            paths.add(Path(p).resolve())
+    return sorted(paths)
+
+
+def _is_under(child: Path, parent: Path) -> bool:
+    """Return True if ``child`` lies under ``parent`` in the filesystem tree."""
+    try:
+        child.relative_to(parent)
+    except ValueError:
+        return False
+    return True
+
+
+def _discover_external_app_base_dirs() -> list[Path]:
+    """Return base dirs of installed Django apps that need explicit @source.
+
+    An app is considered "external" if its path is NOT under ``BASE_DIR``
+    (Tailwind's CWD walk would not reach it) AND NOT under any known
+    site-packages directory (regular pip installs are not user-editable
+    source). This targets the editable-install case from issue #187.
+    """
+    from django.apps import apps
+
+    base_dir = Path(settings.BASE_DIR).resolve()
+    site_packages = _get_site_packages_paths()
+    external: list[Path] = []
+
+    for app_config in apps.get_app_configs():
+        app_path = Path(app_config.path).resolve()
+        if _is_under(app_path, base_dir):
+            continue
+        if any(_is_under(app_path, sp) for sp in site_packages):
+            continue
+        external.append(app_path)
+
+    return sorted(external)
+
+
+def _build_source_css_content(*, use_daisy_ui: bool, inject_external_apps: bool) -> str:
+    """Build the auto-generated source.css content.
+
+    Starts from the minimal ``@import "tailwindcss";`` (+ ``@plugin "daisyui";``
+    when DaisyUI is enabled) and appends one ``@source`` directive per
+    discovered external Django app base dir.
+    """
+    lines = ['@import "tailwindcss";']
+    if use_daisy_ui:
+        lines.append('@plugin "daisyui";')
+
+    if inject_external_apps:
+        external = _discover_external_app_base_dirs()
+        if external:
+            lines.append("")
+            lines.append("/* Auto-generated: installed apps outside BASE_DIR and site-packages. */")
+            for app_path in external:
+                lines.append(f'@source "{app_path}";')
+
+    return "\n".join(lines) + "\n"
+
+
 def _create_standard_config_with_verbose(*, verbose: bool = False) -> None:
     """Create a standard Tailwind CSS config file with optional verbose logging."""
     c = get_config()
@@ -1553,8 +1670,12 @@ def _create_standard_config_with_verbose(*, verbose: bool = False) -> None:
             typer.secho("⏭️  No source CSS path configured, skipping creation", fg=typer.colors.YELLOW)
         return
 
-    # Determine the content based on DaisyUI setting
-    content = DAISY_UI_SOURCE_CSS if c.use_daisy_ui else DEFAULT_SOURCE_CSS
+    # Build content dynamically — includes auto @source directives for
+    # external apps when TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS is enabled.
+    content = _build_source_css_content(
+        use_daisy_ui=c.use_daisy_ui,
+        inject_external_apps=c.auto_source_external_apps,
+    )
 
     if verbose:
         typer.secho(f"📝 Content template: {'DaisyUI' if c.use_daisy_ui else 'Default'}", fg=typer.colors.BLUE)

tests/settings.py

@@ -49,3 +49,10 @@
 USE_TZ = True
 
 SILENCED_SYSTEM_CHECKS = ["staticfiles.W004"]
+
+# Explicit test default (also matches the library default): disable auto
+# @source injection so the generated source.css content is deterministic
+# regardless of how django_tailwind_cli itself happens to be installed in
+# the dev env (editable src/ vs. wheel). Feature tests opt back in
+# explicitly where they exercise the external-app logic.
+TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS = False

tests/test_additional_commands.py

@@ -7,6 +7,7 @@
 
 from pathlib import Path
 from collections.abc import Callable
+from typing import Any
 
 import pytest
 from django.conf import LazySettings
@@ -18,6 +19,11 @@
 from django_tailwind_cli.management.commands.tailwind import handle_command_errors
 
 
+def _call_directly(func: Any, *args: Any, **kwargs: Any) -> Any:
+    """Helper that bypasses django.utils.autoreload.run_with_reloader in tests."""
+    return func(*args, **kwargs)
+
+
 @pytest.fixture(autouse=True)
 def configure_test_settings(settings: LazySettings, tmp_path: Path, mocker: MockerFixture):
     """Configure settings for all tests in this module."""
@@ -191,6 +197,14 @@ def test_optimize_command_basic_output(self, capsys: CaptureFixture[str]):
 class TestErrorHandling:
     """Test error handling decorator and error scenarios."""
 
+    @pytest.fixture(autouse=True)
+    def _bypass_autoreload(self, mocker: MockerFixture):
+        """Bypass django autoreload so watch tests run in-process."""
+        mocker.patch(
+            "django.utils.autoreload.run_with_reloader",
+            side_effect=_call_directly,
+        )
+
     def test_handle_command_errors_decorator_command_error(self, mocker: MockerFixture):
         """Test error decorator handles CommandError properly."""
         mock_exit = mocker.patch("sys.exit")

tests/test_error_scenarios.py

@@ -12,13 +12,15 @@
 import time
 from pathlib import Path
 from collections.abc import Callable
+from typing import Any
 from unittest.mock import Mock, patch
 
 import pytest
 from django.conf import LazySettings
 from django_tailwind_cli.utils import http
 from django.core.management import CommandError, call_command
 from pytest import CaptureFixture
+from pytest_mock import MockerFixture
 from semver import Version
 
 from django_tailwind_cli.config import (
@@ -32,6 +34,11 @@
 from django_tailwind_cli.management.commands.tailwind import ProcessManager
 
 
+def _call_directly(func: Any, *args: Any, **kwargs: Any) -> Any:
+    """Helper that bypasses django.utils.autoreload.run_with_reloader in tests."""
+    return func(*args, **kwargs)
+
+
 class TestConfigurationErrorScenarios:
     """Test configuration validation and error handling."""
 
@@ -226,6 +233,14 @@ def test_version_cache_corruption_handling(self, settings: LazySettings, tmp_pat
 class TestSubprocessErrorScenarios:
     """Test subprocess execution error handling."""
 
+    @pytest.fixture(autouse=True)
+    def _bypass_autoreload(self, mocker: MockerFixture):
+        """Bypass django autoreload so watch tests run in-process."""
+        mocker.patch(
+            "django.utils.autoreload.run_with_reloader",
+            side_effect=_call_directly,
+        )
+
     def test_build_command_execution_failure(self, settings: LazySettings, tmp_path: Path, capsys: CaptureFixture[str]):
         """Test handling of CLI execution failure during build."""
         settings.BASE_DIR = tmp_path