Add asset manifest system for better performance (#212)

* Add asset manifest system for performance optimization

- Added manifest.py module for loading, generating, and saving asset manifests
- Added management command for precomputing template-component relationships
- Updated asset tags to use manifest data with runtime fallback
- Added automatic detection of development mode for improved DX

* Add tests for coverage misses

* Simplify asset manifest by using fixed path

* remove that

* remove comments

* fixes

* updates

* Update docs with asset manifest info

* Improve asset manifest docs with collectstatic integration

* Sort component names in manifest for consistent output

Author: joshuadavidthomas

CHANGELOG.md

@@ -22,6 +22,10 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 - Added `get_component_names_used_in_template` method to ComponentRegistry to access component names used in a template
 - Added `get_component_assets` utility function to staticfiles.py to get assets for a component with optional filtering
+- Added asset manifest system for optimized startup and rendering performance
+- Added `manifest.py` module for generating, loading, and saving asset manifests
+- Added management command `generate_asset_manifest` for pre-computing template-component relationships
+- Added automatic fallback to component scanning in development mode (when DEBUG=True)
 
 ## [0.16.2]
 

docs/assets.md

@@ -133,3 +133,31 @@ python manage.py collectstatic
 ```
 
 This will collect all component assets into your static files directory, allowing you to serve them via your web server, [WhiteNoise](https://whitenoise.readthedocs.io), or a CDN.
+
+## Asset Manifest
+
+For production deployments, django-bird provides a management command to generate an asset manifest:
+
+```bash
+python manage.py generate_asset_manifest
+```
+
+This command creates a manifest file at `STATIC_ROOT/django_bird/manifest.json` that maps templates to their used components. In production mode, this manifest is used to load assets without scanning templates at runtime.
+
+### Integration with collectstatic
+
+For optimal deployment, follow this sequence:
+
+1. Run `python manage.py collectstatic` first to collect all component assets
+2. Then run `python manage.py generate_asset_manifest` to create the manifest file in the collected static files
+
+This ensures that:
+- All component assets are properly collected by the Django staticfiles system
+- The manifest is generated with up-to-date component information
+- The manifest file is placed in the correct location within your static files directory
+
+For automated deployments, you can combine these commands:
+
+```bash
+python manage.py collectstatic --noinput && python manage.py generate_asset_manifest
+```

src/django_bird/management/__init__.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from typing import Any
+from typing import final
+
+from django.core.management.base import BaseCommand
+
+from django_bird._typing import override
+from django_bird.manifest import default_manifest_path
+from django_bird.manifest import generate_asset_manifest
+from django_bird.manifest import save_asset_manifest
+
+
+@final
+class Command(BaseCommand):
+    help: str = (
+        "Generates a manifest of component usage in templates for loading assets"
+    )
+
+    @override
+    def add_arguments(self, parser: ArgumentParser) -> None:
+        parser.add_argument(
+            "--output",
+            type=str,
+            default=None,
+            help="Path where the manifest file should be saved. Defaults to STATIC_ROOT/django_bird/manifest.json",
+        )
+
+    @override
+    def handle(self, *args: Any, **options: Any) -> None:
+        manifest_data = generate_asset_manifest()
+        output_path = options["output"] or default_manifest_path()
+        save_asset_manifest(manifest_data, output_path)
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Asset manifest generated successfully at {output_path}"
+            )
+        )

src/django_bird/management/commands/__init__.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from django.conf import settings
+
+from django_bird.templates import gather_bird_tag_template_usage
+
+logger = logging.getLogger(__name__)
+
+_manifest_cache = None
+
+
+def load_asset_manifest() -> dict[str, list[str]] | None:
+    """Load asset manifest from the default location.
+
+    Returns a simple dict mapping template paths to lists of component names.
+    If the manifest cannot be loaded, returns None and falls back to runtime scanning.
+
+    Returns:
+        dict[str, list[str]] | None: Manifest data or None if not found or invalid
+    """
+    global _manifest_cache
+
+    if _manifest_cache is not None:
+        return _manifest_cache
+
+    if hasattr(settings, "STATIC_ROOT") and settings.STATIC_ROOT:
+        manifest_path = default_manifest_path()
+        if manifest_path.exists():
+            try:
+                with open(manifest_path) as f:
+                    manifest_data = json.load(f)
+                    _manifest_cache = manifest_data
+                    return manifest_data
+            except json.JSONDecodeError:
+                logger.warning(
+                    f"Asset manifest at {manifest_path} contains invalid JSON. Falling back to registry."
+                )
+                return None
+            except (OSError, PermissionError) as e:
+                logger.warning(
+                    f"Error reading asset manifest at {manifest_path}: {str(e)}. Falling back to registry."
+                )
+                return None
+
+    # No manifest found, will fall back to registry
+    return None
+
+
+def generate_asset_manifest() -> dict[str, list[str]]:
+    """Generate a manifest by scanning templates for component usage.
+
+    Returns:
+        dict[str, list[str]]: A dictionary mapping template paths to lists of component names.
+    """
+    template_component_map: dict[str, set[str]] = {}
+    for template_path, component_names in gather_bird_tag_template_usage():
+        # Convert Path objects to strings for JSON
+        template_component_map[str(template_path)] = component_names
+
+    manifest: dict[str, list[str]] = {
+        template: sorted(list(components))
+        for template, components in template_component_map.items()
+    }
+
+    return manifest
+
+
+def save_asset_manifest(manifest_data: dict[str, list[str]], path: Path | str) -> None:
+    """Save asset manifest to a file.
+
+    Args:
+        manifest_data: The manifest data to save
+        path: Path where to save the manifest
+    """
+    path_obj = Path(path)
+    path_obj.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(path_obj, "w") as f:
+        json.dump(manifest_data, f, indent=2)
+
+
+def default_manifest_path() -> Path:
+    """Get the default manifest path.
+
+    Returns:
+        Path: The default path for the asset manifest file
+    """
+    if hasattr(settings, "STATIC_ROOT") and settings.STATIC_ROOT:
+        return Path(settings.STATIC_ROOT) / "django_bird" / "manifest.json"
+    else:
+        # Fallback for when STATIC_ROOT is not set
+        return Path("django_bird-asset-manifest.json")

src/django_bird/management/commands/generate_asset_manifest.py

@@ -5,11 +5,13 @@
 from typing import final
 
 from django import template
+from django.conf import settings
 from django.template.base import Parser
 from django.template.base import Token
 from django.template.context import Context
 
 from django_bird._typing import override
+from django_bird.manifest import load_asset_manifest
 
 
 class AssetTag(Enum):
@@ -35,18 +37,40 @@ def __init__(self, asset_tag: AssetTag):
     @override
     def render(self, context: Context) -> str:
         from django_bird.components import components
+        from django_bird.staticfiles import Asset
+        from django_bird.staticfiles import get_component_assets
 
         template = getattr(context, "template", None)
         if not template:
             return ""
-        used_components = components.get_component_usage(template.origin.name)
-        assets = set(
-            asset
-            for component in used_components
-            for asset in component.assets
-            if asset.type.tag == self.asset_tag
-        )
+
+        template_path = template.origin.name
+
+        used_components = []
+
+        # Only use manifest in production mode
+        if not settings.DEBUG:
+            manifest = load_asset_manifest()
+            if manifest and template_path in manifest:
+                # Use manifest for component names in production
+                component_names = manifest[template_path]
+                used_components = [
+                    components.get_component(name) for name in component_names
+                ]
+
+        # If we're in development or there was no manifest data, use registry
+        if not used_components:
+            used_components = list(components.get_component_usage(template_path))
+
+        assets: set[Asset] = set()
+        for component in used_components:
+            component_assets = get_component_assets(component)
+            assets.update(
+                asset for asset in component_assets if asset.type.tag == self.asset_tag
+            )
+
         if not assets:
             return ""
+
         rendered = [asset.render() for asset in sorted(assets, key=lambda a: a.path)]
         return "\n".join(rendered)