Add Jinja2 template support for ReactPy components

- Created `ReactPyExtension` Jinja2 extension with `component`,
  `pyscript_component`, and `pyscript_setup` globals that delegate to the
  existing Django template tag implementations.
- Refactored `reactpy.py` to export template name constants
  (COMPONENT_TEMPLATE, PYSCRIPT_COMPONENT_TEMPLATE, PYSCRIPT_SETUP_TEMPLATE)
  so they can be reused by the Jinja2 extension.
- Added JINJA_COMPONENT_REGEX to utils.py's RootComponentFinder so that
  {{ component(...) }} syntax in Jinja2 templates is auto-detected.
- Added test infrastructure: settings_jinja.py, jinja_env.py, jinja_views.py,
  jinja_urls.py, Jinja2 template files, and test_jinja.py.
- Made test_app/__init__.py gracefully handle missing `bun` binary by
  skipping the JS rebuild when artifacts already exist.
- Added jinja2 to pyproject.toml hatch-test extra-dependencies.
- Updated CHANGELOG.md.

(cherry picked from commit 3923cee)

Author: User

CHANGELOG.md

@@ -22,6 +22,7 @@ Don't forget to remove deprecated code on each major release!
 ### Added
 
 - Automatically serve ReactPy wheel from Django's static directory when using PyScript.
+- Jinja2 template support via `reactpy_django.templatetags.jinja.ReactPyExtension`.
 
 ### Changed
 

pyproject.toml

@@ -97,6 +97,7 @@ extra-dependencies = [
   "django-bootstrap5",
   "decorator",
   "uvicorn[standard]",
+  "jinja2",
 ]
 matrix-name-format = "{variable}-{value}"
 

src/reactpy_django/templatetags/jinja.py

@@ -1,59 +1,210 @@
 """
-Jinja support.
+Jinja2 template support for ReactPy-Django.
+
+Provides Jinja2 global functions that mirror the functionality of Django's
+``{% component %}``, ``{% pyscript_component %}``, and ``{% pyscript_setup %}``
+template tags. These are registered as environment globals so they can be
+called directly from Jinja2 templates via ``{{ component(...) }}`` syntax.
+
+To enable, add the extension to your Jinja2 environment configuration:
+
+.. code-block:: python
+
+    TEMPLATES = [
+        {
+            "BACKEND": "django.template.backends.jinja2.Jinja2",
+            "DIRS": [...],
+            "OPTIONS": {
+                "environment": "myproject.jinja_env.environment",
+            },
+        },
+    ]
+
+Then in ``myproject/jinja_env.py``:
+
+.. code-block:: python
+
+    from jinja2 import Environment
+    from reactpy_django.templatetags.jinja import ReactPyExtension
+
+    def environment(**options):
+        env = Environment(**options)
+        env.add_extension(ReactPyExtension)
+        return env
 """
+
+from __future__ import annotations
+
+import json
+from logging import getLogger
+from typing import TYPE_CHECKING
+
 from django.template import RequestContext, loader
+from django.utils.safestring import mark_safe
 from jinja2 import pass_context
 from jinja2.ext import Extension
 from jinja2.runtime import Context
-from reactpy_django.templatetags.reactpy import COMPONENT_TEMPLATE, component
+
+from reactpy_django.templatetags.reactpy import (
+    COMPONENT_TEMPLATE,
+    PYSCRIPT_COMPONENT_TEMPLATE,
+    PYSCRIPT_SETUP_TEMPLATE,
+    component as django_component_tag,
+    pyscript_component as django_pyscript_component_tag,
+    pyscript_setup as django_pyscript_setup_tag,
+)
+
+if TYPE_CHECKING:
+    from reactpy.types import Component, VdomDict
+
+_logger = getLogger(__name__)
 
 
 class ReactPyExtension(Extension):
-    """
-    Jinja has more expressive power than core Django's templates, and can
-    directly handle expansions such as:
+    """A Jinja2 extension that adds ReactPy component rendering functions.
 
-        {{ component(*args, **kwargs) }}
+    This extension registers the following globals into the Jinja2 environment:
+
+    * ``component`` - Renders a server-side ReactPy component.
+    * ``pyscript_component`` - Renders a client-side PyScript component.
+    * ``pyscript_setup`` - Renders PyScript setup configuration.
+
+    Unlike Django's template tags, which require ``{% load reactpy %}`` and use
+    ``{% component %}`` syntax, Jinja2 uses ``{{ component(...) }}`` function calls.
+    This is because Jinja2 has more expressive power and can directly handle
+    function expansions.
     """
 
-    #
-    # Therefore, there is no new tag to parse().
-    #
     tags = {}
 
     def __init__(self, environment):
         super().__init__(environment)
-        #
-        # All we need is to add global "component" to the environment.
-        #
-        environment.globals["component"] = self.template_tag
+        environment.globals["component"] = self._component
+        environment.globals["pyscript_component"] = self._pyscript_component
+        environment.globals["pyscript_setup"] = self._pyscript_setup
 
     @pass_context
-    def template_tag(
-        self, jinja_context: Context, dotted_path: str, *args, **kwargs
+    def _component(
+        self,
+        jinja_context: Context,
+        dotted_path: str,
+        *args,
+        host: str | None = None,
+        prerender: str = "",
+        offline: str = "",
+        **kwargs,
     ) -> str:
-        """
-        This method is used to embed an existing ReactPy component into your
-        Jinja2 template.
+        """Render a server-side ReactPy component.
+
+        This is the Jinja2 equivalent of ``{% component "path.to.Component" %}``.
 
         Args:
-            dotted_path: String of the fully qualified name of a component.
-            *args: The positional arguments to provide to the component.
+            dotted_path: The dotted path to the component to render.
+            *args: Positional arguments to pass to the component.
+            host: The host to use for ReactPy connections.
+            prerender: If ``"true"`` the component will be pre-rendered server-side.
+            offline: Dotted path to an offline fallback component.
+            **kwargs: Keyword arguments to pass to the component.
 
-        Keyword Args:
-            **kwargs: The keyword arguments to provide to the component.
+        Returns:
+            Rendered HTML string.
+        """
+        request = jinja_context.parent.get("request")
+        if request is None:
+            _logger.exception(
+                "Cannot render a ReactPy component in a Jinja2 template without a "
+                "request object. Ensure the 'django.template.context_processors.request' "
+                "context processor is enabled for your Jinja2 backend."
+            )
+            return ""
+
+        django_context = RequestContext(
+            request,
+            autoescape=jinja_context.eval_ctx.autoescape,
+        )
+        template_context = django_component_tag(
+            django_context,
+            dotted_path,
+            *args,
+            host=host,
+            prerender=prerender,
+            offline=offline,
+            **kwargs,
+        )
+        return loader.render_to_string(
+            COMPONENT_TEMPLATE,
+            template_context,
+            request,
+        )
+
+    @pass_context
+    def _pyscript_component(
+        self,
+        jinja_context: Context,
+        *file_paths: str,
+        initial: str | VdomDict | Component = "",
+        root: str = "root",
+    ) -> str:
+        """Render a client-side PyScript component.
+
+        This is the Jinja2 equivalent of ``{% pyscript_component "path/to/file.py" %}``.
+
+        Args:
+            file_paths: File paths to client-side component Python files.
+            initial: Initial HTML displayed before the PyScript component loads.
+            root: The name of the root component function.
 
         Returns:
-            Whatever the components returns.
+            Rendered HTML string.
         """
+        request = jinja_context.parent.get("request")
+        if request is None:
+            _logger.exception(
+                "Cannot render a PyScript component in a Jinja2 template without a "
+                "request object."
+            )
+            return ""
+
         django_context = RequestContext(
-            jinja_context.parent["request"],
+            request,
             autoescape=jinja_context.eval_ctx.autoescape,
         )
-        template_context = component(django_context, dotted_path, *args, **kwargs)
-        #
-        # TODO: can this be usefully cached?
-        #
+        template_context = django_pyscript_component_tag(
+            django_context,
+            *file_paths,
+            initial=initial,
+            root=root,
+        )
+        return loader.render_to_string(
+            PYSCRIPT_COMPONENT_TEMPLATE,
+            template_context,
+            request,
+        )
+
+    def _pyscript_setup(
+        self,
+        *extra_py: str,
+        extra_js: str | dict = "",
+        config: str | dict = "",
+    ) -> str:
+        """Render PyScript setup configuration.
+
+        This is the Jinja2 equivalent of ``{% pyscript_setup %}``.
+
+        Args:
+            extra_py: Additional Python dependencies.
+            extra_js: Additional JavaScript modules.
+            config: PyScript configuration overrides.
+
+        Returns:
+            Rendered HTML string.
+        """
+        template_context = django_pyscript_setup_tag(
+            *extra_py,
+            extra_js=extra_js,
+            config=config,
+        )
         return loader.render_to_string(
-            COMPONENT_TEMPLATE, template_context, jinja_context.parent["request"]
+            PYSCRIPT_SETUP_TEMPLATE,
+            template_context,
         )

src/reactpy_django/templatetags/reactpy.py

@@ -46,6 +46,8 @@
     _logger.exception("Could not resolve the 'web_modules' URL path!")
 
 COMPONENT_TEMPLATE = "reactpy/component.html"
+PYSCRIPT_COMPONENT_TEMPLATE = "reactpy/pyscript_component.html"
+PYSCRIPT_SETUP_TEMPLATE = "reactpy/pyscript_setup.html"
 
 
 @register.inclusion_tag(COMPONENT_TEMPLATE, takes_context=True)
@@ -192,7 +194,7 @@ def component(
     }
 
 
-@register.inclusion_tag("reactpy/pyscript_component.html", takes_context=True)
+@register.inclusion_tag(PYSCRIPT_COMPONENT_TEMPLATE, takes_context=True)
 def pyscript_component(
     context: template.RequestContext,
     *file_paths: str,
@@ -226,7 +228,7 @@ def pyscript_component(
     }
 
 
-@register.inclusion_tag("reactpy/pyscript_setup.html")
+@register.inclusion_tag(PYSCRIPT_SETUP_TEMPLATE)
 def pyscript_setup(
     *extra_py: str,
     extra_js: str | dict = "",