Adds ADD_ASSET_PREFIX setting for configuring staticfiles url prefix (#226)

Author: joshuadavidthomas

CHANGELOG.md

@@ -18,6 +18,10 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### Added
+
+- Added new `ADD_ASSET_PREFIX` setting to control how the app label prefix is added to asset URLs. This setting provides more flexibility than the previous DEBUG-based behavior, especially useful in test environments.
+
 ### Fixed
 
 - Fixed path normalization in asset manifest to prevent double-prefixing of already normalized paths (e.g., preventing "app:app:templates/file.html").

docs/configuration.md

@@ -58,6 +58,7 @@ from pathlib import Path
 DJANGO_BIRD = {
     "COMPONENT_DIRS": list[Path | str] = [],
     "ENABLE_BIRD_ATTRS": bool = True,
+    "ADD_ASSET_PREFIX": bool | None = None,
 }
 ```
 
@@ -110,3 +111,25 @@ The default `bird` directory will always be checked last, ensuring that your cus
 Controls whether components automatically receive data attributes related to django-bird in its `attrs` template context variable. Defaults to `True`.
 
 See [Component ID Attribute](params.md#component-id-attribute) for more details on how this works.
+
+### `ADD_ASSET_PREFIX`
+
+Controls whether the app label prefix (`django_bird/`) is added to component asset URLs. This setting has three possible values:
+
+- `None` (default): Automatically add the prefix in production (when `DEBUG = False`) but not in development mode. This matches Django's standard behavior where staticfiles are served directly from source directories in development but collected into a central location in production.
+
+- `True`: Always add the prefix, regardless of the `DEBUG` setting. This is useful if you want consistent URL paths in all environments.
+
+- `False`: Never add the prefix, regardless of the `DEBUG` setting. This is useful for custom static file configurations or when you're manually managing the directory structure.
+
+#### Example Use Cases
+
+- **Testing Environment**: In test environments, especially with Playwright or Selenium e2e tests, you may want to set:
+
+  ```python
+  DJANGO_BIRD = {"ADD_ASSET_PREFIX": False}
+  ```
+
+  This ensures your tests can find static assets without the prefix, even when `DEBUG = False`.
+
+- **Custom Static File Handling**: If you have a custom static file setup that doesn't follow Django's conventions, you can configure the appropriate value based on your needs.

src/django_bird/conf.py

@@ -19,6 +19,7 @@
 class AppSettings:
     COMPONENT_DIRS: list[Path | str] = field(default_factory=list)
     ENABLE_BIRD_ATTRS: bool = True
+    ADD_ASSET_PREFIX: bool | None = None
 
     @override
     def __getattribute__(self, __name: str) -> object:
@@ -28,5 +29,13 @@ def __getattribute__(self, __name: str) -> object:
     def get_component_directory_names(self):
         return unique_ordered([*self.COMPONENT_DIRS, "bird"])
 
+    def should_add_asset_prefix(self) -> bool:
+        """Determine if the app label prefix should be added to asset URLs."""
+        if self.ADD_ASSET_PREFIX is not None:
+            return self.ADD_ASSET_PREFIX
+
+        # Fall back to the DEBUG setting (add prefix in production)
+        return not settings.DEBUG
+
 
 app_settings = AppSettings()

src/django_bird/staticfiles.py

@@ -12,7 +12,6 @@
 from typing import final
 from typing import overload
 
-from django.conf import settings
 from django.contrib.staticfiles import finders
 from django.contrib.staticfiles.finders import BaseFinder
 from django.contrib.staticfiles.storage import StaticFilesStorage
@@ -179,11 +178,16 @@ def __init__(self, *args: Any, prefix: str, **kwargs: Any):
     def url(self, name: str | None) -> str:
         if name is None:
             return super().url(name)
-        # Only add prefix in production (when DEBUG is False)
+        # Determine if we should add the prefix based on the app settings
+        from .conf import app_settings
+
+        # Add prefix based on app settings configuration
         # In development, asset paths don't include the app label prefix
-        # because they come directly from source directories and in production,
-        # assets are collected to STATIC_ROOT/django_bird/
-        if not settings.DEBUG and not name.startswith(f"{self.prefix}/"):
+        # because they come directly from source directories
+        # In production, assets are collected to STATIC_ROOT/django_bird/
+        if app_settings.should_add_asset_prefix() and not name.startswith(
+            f"{self.prefix}/"
+        ):
             name = f"{self.prefix}/{name}"
         return super().url(name)
 

tests/test_staticfiles.py

@@ -225,6 +225,40 @@ def test_url(self, DEBUG, expected_prefix, templates_dir):
                 == f"{expected_prefix}/{button_css.file.parent.name}/{button_css.file.name}"
             )
 
+    @pytest.mark.parametrize(
+        "add_prefix,DEBUG,expected_prefix",
+        [
+            (None, False, "/static/django_bird"),
+            (None, True, "/static"),
+            (True, False, "/static/django_bird"),
+            (True, True, "/static/django_bird"),
+            (False, False, "/static"),
+            (False, True, "/static"),
+        ],
+    )
+    def test_url_with_add_asset_prefix(
+        self, add_prefix, DEBUG, expected_prefix, templates_dir, override_app_settings
+    ):
+        button = TestComponent(
+            name="button",
+            content="<button>Click me</button>",
+        ).create(templates_dir)
+        button_css = TestAsset(
+            component=button,
+            content=".button { color: blue; }",
+            asset_type=CSS,
+        ).create()
+
+        component = Component.from_name(button.name)
+        asset = component.get_asset(button_css.file.name)
+
+        with override_settings(DEBUG=DEBUG):
+            with override_app_settings(ADD_ASSET_PREFIX=add_prefix):
+                assert (
+                    asset.url
+                    == f"{expected_prefix}/{button_css.file.parent.name}/{button_css.file.name}"
+                )
+
     def test_url_nonexistent(self, templates_dir):
         button = TestComponent(
             name="button",