Jinja

Overview¶

ReactPyJinja adds three tags to a Jinja2 environment so an existing Python web app can mount ReactPy components inside templates it already owns — one tag for server-rendered components, two for components that run in the browser via PyScript.

{% component "my_app.pages.counter" %}

Install the extra the extension needs:

pip install "reactpy[asgi,jinja]"

It lives at reactpy.templatetags.ReactPyJinja. Despite the templatetags name it is not a Django app — it is a jinja2-simple-tags StandaloneTag, so it works with any Jinja2 environment.

Reference¶

Registering the extension¶

Two equivalent forms:

from jinja2 import Environment, FileSystemLoader

from reactpy.templatetags import ReactPyJinja

# at construction
env = Environment(loader=FileSystemLoader("templates"), extensions=[ReactPyJinja])

# or afterwards
env = Environment(loader=FileSystemLoader("templates"))
env.add_extension(ReactPyJinja)

Both register all three tags at once; there is no way to register one alone, and no configuration to pass. Registering ReactPyJinja(...) as an instance and calling .register() does not work — that object has no register method.

{% component "dotted.path" %}¶

Emits the markup that mounts a server-side component: an empty mount element, an import-map fallback, and a module script that calls mountReactPy.

{% component "my_app.pages.counter" %}
{% component "my_app.pages.badge", class="badge" %}

• The dotted path (required): the import path of the root component function — the same string you give ReactPyMiddleware's root_components. It is embedded verbatim into the emitted JavaScript; ReactPy imports it on the server when the browser asks to connect.
• class (optional): a CSS class for the generated mount element, producing <div id="..." class="badge"></div>.

safe_output is set on the tag, so Jinja does not escape the returned HTML even under autoescape=True.

Errors this tag raises¶

A wrong dotted path is not one of them. Nothing checks that the module or attribute exists: the tag happily emits markup pointing at a path that will never connect, and the only symptom is a permanently empty element plus a failed request in the browser console. Verify the path against what you passed to root_components.

{% pyscript_setup %}¶

Emits the PyScript bootstrap — stylesheet, module script, and the config that installs ReactPy into the browser.

<head>
    {% pyscript_setup %}
</head>

• extra_py (optional, positional, repeatable): extra Python packages for the PyScript runtime — {% pyscript_setup "numpy", "rich" %}. They are appended to the package list alongside ReactPy's own wheel.
• extra_js (optional, keyword): a JSON object mapping module URLs to names, e.g. extra_js='{"./my.js": "mylib"}'. It is merged into the config's js_modules.main. A plain string that is not valid JSON raises json.decoder.JSONDecodeError.
• config (optional, keyword): a JSON object (or JSON string) merged over the generated config, letting you set anything PyScript accepts.

Put this tag in the document head, once. A page with several pyscript_component tags needs one bootstrap, not one per component.

{% pyscript_component "path/to/file.py" %}¶

Emits a <div> plus a <script type='py'> that runs the named file's component in the browser.

{% pyscript_component "components/counter.py" initial="Loading..." %}

• File paths (required, positional, repeatable): paths to Python files, resolved relative to the process's current working directory at template-render time. Several files may be passed; they are concatenated into one script.
• initial (optional): markup rendered inside the mount element while PyScript boots.
• root (optional): the name of the root component function, default "root".

Because the files are read and inlined, the browser never fetches them and your app serves no route for them.

Both are raised at render time, so they surface as a 500 on the page — not as a broken widget.

Usage¶

A server-rendered component in an existing page¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

templates = Jinja2Templates(
    env=Environment(
        loader=FileSystemLoader("templates"),
        extensions=[ReactPyJinja],
        autoescape=True,
    )
)


async def home(request):
    return templates.TemplateResponse(request, "home.html")


starlette_app = Starlette(routes=[Route("/", home)])

# The dotted path must be importable by the server: the browser asks ReactPy to
# render `pages.counter`, and that lookup happens on the server, not in the
# template. Register the same path here that the template passes to the tag.
my_app = ReactPyMiddleware(starlette_app, root_components=["main.counter"])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<!doctype html>
<html lang="en">

<head>
  <title>Accounts</title>
</head>

<body>
  <h1>Welcome</h1>

  {# One tag per component; ReactPy gives each mount element its own id. #}
  {% component "pages.counter" %}

  {# `class` must follow a comma -- the tag parses its arguments as Python. #}
  {% component "pages.badge", class="badge" %}
</body>

</html>

1

# TODO

The component must live in an importable module, since the browser reaches it by dotted path — a component defined inside the view function is not reachable that way. The template's path and the root_components list have to agree exactly.

A client-side component¶

Setup in the head, the component where it belongs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<!doctype html>
<html lang="en">
  <head>
    <title>Counter</title>
    {% pyscript_setup %}
  </head>
  <body>
    {% pyscript_component "components/counter.py" initial="Loading..." %}
  </body>
</html>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

@component
def root():
    # `root` is the name the tag looks for by default; pass root="other" to
    # point it somewhere else. This file is inlined into the page at render
    # time and runs in the browser, so treat all of it as public.
    count, set_count = use_state(0)
    return html.div(
        html.h1(count),
        html.button({"onClick": lambda event: set_count(count + 1)}, "Add 1"),
    )

1

# TODO

There is no websocket, so use_connection, use_scope, and use_location have no connection to read and raise — see Use Connection.

Which one to use¶

Related¶

• Add React to an Existing Project — the full Starlette wiring these tags are for
• ReactPyMiddleware — the middleware that serves server-rendered components, and the markup this tag generates
• ReactPyCsr — the ASGI-app form of the PyScript tags
• ReactPy — standalone server-rendered app
• Common Props — what a component may return