Better handling for source.css File.

Author: oliverandrich

CHANGELOG.md

@@ -2,19 +2,30 @@
 
 ## 4.2.0
 
-> [!WARNING]
+> [!CAUTION]
 > Version 4.2.x and onward only support Tailwind CSS 4.x. If you are using Tailwind CSS 3.x,
 > please use version 2.21.1 of this library. Version 4.0.x or 4.1.x still support Tailwind CSS 3.x, but
 > these versions are not recommended to use for new projects.
 
+> [!CAUTION]
+> This version includes changes to the handling of `TAILWIND_CLI_PATH` and `TAILWIND_CLI_SRC_CSS`.
+
 - Default fallback version is now 4.1.3.
 - Removed support for Tailwind CSS 3.x. The main reason is that this makes the library easier to maintain and also add better support for custom CLI builds which support DaisyUI and other plugins.
 - django-tailwind-cli now uses proper platform directories to store the CLI binary.
-  - The proper directories are powered by [platformdirs](https://pypi.org/project/platformdirs/).
-  - TAILWIND_CLI_PATH is now optional by default.
-  - If TAILWIND_CLI_PATH is None, the binary is stored in `user_data_dir("django-tailwind-cli", "django-commons")`.
-  - The library doesn't rely anylonger on a properly set `settings.BASE_DIR`.
-- TAILWIND_CLI_ASSET_NAME is also used for the downloaded CLI to distinguish between `tailwindcss` and `tailwindcss-extra`.
+
+    * The proper directories are powered by [platformdirs](https://pypi.org/project/platformdirs/).
+    * `TAILWIND_CLI_PATH` is now optional by default.
+    * If `TAILWIND_CLI_PATH` is None, the binary is stored in `user_data_dir("django-tailwind-cli", "django-commons")`.
+    * The library doesn't rely anylonger on a properly set `settings.BASE_DIR`.
+
+- `TAILWIND_CLI_ASSET_NAME` is also used for the downloaded CLI to distinguish between `tailwindcss` and `tailwindcss-extra`.
+- The behaviour of `TAILWIND_CLI_SRC_CSS` has been changed. The reasoning behind this change was, less default code inside the project and whitenoise had issues with a CSS file inside an asset folder referencing non-existing imports.
+
+    * It defaults to `None`.
+    * If it is `None` the default input file is created in the user cache directory.
+    * If it is a relative path, this path is considered relative to `settings.BASE_DIR`.
+    * The last option is an absolute path.
 
 ## 4.1.0
 

docs/settings.md

@@ -29,15 +29,14 @@ your project.
 
     This allows you to override the default of the library where to store the CLI binary.
 
-    The default behaviour is to store the CLI binary in directory return by this call `platformdirs.user_data_dir("django-tailwind-cli", "django-commons")`. Checkout [platformdirs](https://pypi.org/project/platformdirs/) for details.
+    The default behaviour is to store the CLI binary in the directory returned by this call `platformdirs.user_data_dir("django-tailwind-cli", "django-commons")`. Checkout [platformdirs](https://pypi.org/project/platformdirs/) for details.
 
     But if you want to store it elsewhere or plan to use a custom build binary stored locally, change this setting either to a path to a directory or the full path to the binary. If it points to a directory, this is the download destination otherwise it directly tries to use the referenced binary.
 
-    !!! warning
-
-        If you use the new option from **2.7.0** but haven't installed a binary before running any of the management commands, these commands will treat the configured path as a directory and create it, if it is missing. Afterwards the official CLI will be downloaded to this path.
-
-        In case you want to use the new behaviour, it is highly recommended to also set the new setting `TAILWIND_CLI_AUTOMATIC_DOWNLOAD` to `False`.
+    > [!Warning]
+    > If you use the new option from **2.7.0** but haven't installed a binary before running any of the management commands, these commands will treat the configured path as a directory and create it, if it is missing. Afterwards the official CLI will be downloaded to this path.
+    >
+    > In case you want to use the new behaviour, it is highly recommended to also set the new setting `TAILWIND_CLI_AUTOMATIC_DOWNLOAD` to `False`.
 
 `TAILWIND_CLI_AUTOMATIC_DOWNLOAD`
 : **Default**: `True`
@@ -49,9 +48,8 @@ your project.
 
     Specifies the repository from which the CLI is downloaded. This is useful if you are using a customized version of the CLI, such as [tailwind-cli-extra](https://github.com/dobicinaitis/tailwind-cli-extra).
 
-    !!! warning
-
-        If you use this option, ensure that you update the `TAILWIND_CLI_VERSION` to match the version of the customized CLI you are using. Additionally, you may need to update the `TAILWIND_CLI_ASSET_NAME` if the asset name is different. See the example below.
+    > [!Warning]
+    > If you use this option, ensure that you update the `TAILWIND_CLI_VERSION` to match the version of the customized CLI you are using. Additionally, you may need to update the `TAILWIND_CLI_ASSET_NAME` if the asset name is different. See the example below.
 
 `TAILWIND_CLI_ASSET_NAME`:
 : **Default**: `"tailwindcss"`
@@ -60,22 +58,24 @@ your project.
 
     This option is particularly useful if the customized repository you are using has a different name for the Tailwind CLI asset. For example, the asset name for [tailwind-cli-extra](https://github.com/dobicinaitis/tailwind-cli-extra/releases/latest/) is `tailwindcss-extra`.
 
-    !!! Note
-
-        Here is a full example of using a custom repository and asset name:
+    > [!Note]
+    > Here is a full example of using a custom repository and asset name:
+    >    ```python
+    >    TAILWIND_CLI_SRC_REPO = "dobicinaitis/tailwind-cli-extra"
+    >    TAILWIND_CLI_ASSET_NAME = "tailwindcss-extra"
+    >    ```
 
-        ```python
-        TAILWIND_CLI_SRC_REPO = "dobicinaitis/tailwind-cli-extra"
-        TAILWIND_CLI_ASSET_NAME = "tailwindcss-extra"
-        TAILWIND_CLI_VERSION = "2.1.4"
-        ```
 
 `TAILWIND_CLI_SRC_CSS`
-**Default** (for Tailwind 4.x): `css/source.css`
+**Default**: `None`
+
+    This variable can be set to `None`, a relative path and an absolute path.
+
+    If it is set to `None`, the library creates file with the name `source.css` in the directory returned by this call `platformdirs.user_cache_dir("django-tailwind-cli", "django-commons")`. Checkout [platformdirs](https://pypi.org/project/platformdirs/) for details.
+
+    If it is a relative path it is assumed to be relative to `settings.BASE_DIR`. If `settings.BASE_DIR` is not defined or the file doesn't exist a `ValueError` is raised.
 
-    For **Tailwind CSS 4.x** this required file is used to configure Tailwind CSS and also add
-    additional CSS rules for your project. This file is stored relative to the first element of
-    the `STATICFILES_DIRS` array.
+    If it is an absolute path, this path is used as the input file for Tailwind CSS CLI. If the path doesn't exist, a `ValueError`is raised.
 
 `TAILWIND_CLI_DIST_CSS`
 : **Default**: `"css/tailwind.css"`

src/django_tailwind_cli/config.py

@@ -27,28 +27,26 @@ class Config:
     def watch_cmd(self) -> list[str]:
         result = [
             str(self.cli_path),
+            "--input",
+            str(self.src_css),
             "--output",
             str(self.dist_css),
             "--watch",
         ]
 
-        if self.src_css:
-            result.extend(["--input", str(self.src_css)])
-
         return result
 
     @property
     def build_cmd(self) -> list[str]:
         result = [
             str(self.cli_path),
+            "--input",
+            str(self.src_css),
             "--output",
             str(self.dist_css),
             "--minify",
         ]
 
-        if self.src_css:
-            result.extend(["--input", str(self.src_css)])
-
         return result
 
 
@@ -123,8 +121,7 @@ def get_config() -> Config:
         cli_path = cli_path.expanduser() / f"{asset_name}-{system}-{machine}-{version_str}{extension}"
 
     # Determine the download url for the cli
-    if not (repo_url := getattr(settings, "TAILWIND_CLI_SRC_REPO", "tailwindlabs/tailwindcss")):
-        raise ValueError("TAILWIND_CLI_SRC_REPO must not be None.")
+    repo_url = getattr(settings, "TAILWIND_CLI_SRC_REPO", "tailwindlabs/tailwindcss")
     download_url = (
         f"https://github.com/{repo_url}/releases/download/v{version_str}/{asset_name}-{system}-{machine}{extension}"
     )
@@ -135,9 +132,14 @@ def get_config() -> Config:
     dist_css = Path(settings.STATICFILES_DIRS[0]) / dist_css_base
 
     # Determine the full path to the source css file.
-    if not (src_css := getattr(settings, "TAILWIND_CLI_SRC_CSS", "css/source.css")):
-        raise ValueError("TAILWIND_CLI_SRC_CSS must not be None.")
-    src_css = Path(settings.STATICFILES_DIRS[0]) / src_css
+    src_css = getattr(settings, "TAILWIND_CLI_SRC_CSS", None)
+    if not src_css:
+        user_cache_dir = platformdirs.user_cache_dir("django-tailwind-cli", "django-commons")
+        src_css = Path(user_cache_dir) / "source.css"
+    else:
+        src_css = Path(src_css)
+        if not src_css.is_absolute():
+            src_css = Path(settings.BASE_DIR) / src_css
 
     # Determine if the CLI should be downloaded automatically
     automatic_download = getattr(settings, "TAILWIND_CLI_AUTOMATIC_DOWNLOAD", True)

src/django_tailwind_cli/management/commands/tailwind.py

@@ -32,7 +32,7 @@ def build() -> None:
         typer.secho(f"Built production stylesheet '{config.dist_css}'.", fg=typer.colors.GREEN)
     except KeyboardInterrupt:
         typer.secho("Canceled building production stylesheet.", fg=typer.colors.RED)
-    except subprocess.CalledProcessError as e:
+    except subprocess.CalledProcessError as e:  # pragma: no cover
         error_message = e.stderr if e.stderr else "An unknown error occurred."
         typer.secho(f"Failed to build production stylesheet: {error_message}", fg=typer.colors.RED)
         sys.exit(1)

tests/test_config.py

@@ -85,7 +85,7 @@ def test_default_config():
     )
     assert str(c.dist_css) == "/home/user/project/assets/css/tailwind.css"
     assert c.src_css is not None
-    assert str(c.src_css) == "/home/user/project/assets/css/source.css"
+    assert str(c.src_css).endswith("django-tailwind-cli/source.css")
 
 
 def test_invalid_settings_for_staticfiles_dirs(settings: SettingsWrapper):
@@ -116,12 +116,6 @@ def test_invalid_settings_for_tailwind_cli_src_repo(settings: SettingsWrapper):
         get_config()
 
 
-def test_invalid_settings_for_tailwind_cli_src_css(settings: SettingsWrapper):
-    settings.TAILWIND_CLI_SRC_CSS = None
-    with pytest.raises(ValueError, match="TAILWIND_CLI_SRC_CSS must not be None."):
-        get_config()
-
-
 @pytest.mark.parametrize(
     "platform,machine,result",
     [
@@ -215,21 +209,21 @@ def test_build_cmd():
     c = get_config()
     assert c.build_cmd == [
         str(c.cli_path),
+        "--input",
+        str(c.src_css),
         "--output",
         str(c.dist_css),
         "--minify",
-        "--input",
-        str(c.src_css),
     ]
 
 
 def test_watch_cmd():
     c = get_config()
     assert c.watch_cmd == [
         str(c.cli_path),
+        "--input",
+        str(c.src_css),
         "--output",
         str(c.dist_css),
         "--watch",
-        "--input",
-        str(c.src_css),
     ]

tests/test_management_commands.py

@@ -16,6 +16,7 @@ def configure_settings(request: pytest.FixtureRequest, mocker: MockerFixture, se
     settings.BASE_DIR = tmp_path
     settings.TAILWIND_CLI_PATH = tmp_path
     settings.TAILWIND_CLI_VERSION = request.param
+    settings.TAILWIND_CLI_SRC_CSS = tmp_path / "source.css"
     settings.STATICFILES_DIRS = (settings.BASE_DIR / "assets",)
 
     mocker.resetall()
@@ -32,8 +33,6 @@ def test_calling_unknown_subcommand():
 
 
 def test_create_src_css_if_non_exists(settings: LazySettings, tmp_path: Path):
-    if settings.TAILWIND_CLI_VERSION == "3.4.17":
-        pytest.skip("With Tailwind CSS CLI 3.4.17 a src css file is optional. But with 4.0.0 it is required.")
     c = get_config()
     assert c.src_css is not None
     assert not c.src_css.exists()
@@ -43,8 +42,6 @@ def test_create_src_css_if_non_exists(settings: LazySettings, tmp_path: Path):
 
 
 def test_with_existing_src_css(settings: LazySettings, tmp_path: Path):
-    if settings.TAILWIND_CLI_VERSION == "3.4.17":
-        pytest.skip("With Tailwind CSS CLI 3.4.17 a src css file is optional. But with 4.0.0 it is required.")
     c = get_config()
     assert c.src_css is not None
     c.src_css.parent.mkdir(parents=True, exist_ok=True)