WIP: feat: native React client via client_type="react" by patrickoleary · Pull Request #69 · Kitware/trame-client

patrickoleary · 2026-08-28T20:49:49Z

Summary

Add a React client (react-app/) as a peer of vue2-app/vue3-app. The server
side is unchanged: when client_type == "react", the widget tree serializes
to a JSON component tree (utils/react.py) pushed through the same
trame__template_* state keys, and the client renders it natively with
React.createElement.

widgets/core.py: structured attribute capture alongside the Vue string
formatting (vue output byte-identical, regression-tested), react_node
property, and r_* directive aliases (r_if/r_show/r_for/r_model/r_bind_/
r_on_) for React-flavored apps
react-app/: registry + renderer (expression evaluation against the shared
state, conditionals, lists, controlled-component models, scoped slots,
event modifiers), 14 built-in component ports, vite build into
module/react-www
module/react.py + ui/core.py flush branch for the react client type

Add a React client (react-app/) as a peer of vue2-app/vue3-app. The server side is unchanged: when client_type == "react", the widget tree serializes to a JSON component tree (utils/react.py) pushed through the same trame__template_* state keys, and the client renders it natively with React.createElement. - widgets/core.py: structured attribute capture alongside the Vue string formatting (vue output byte-identical, regression-tested), react_node property, and r_* directive aliases (r_if/r_show/r_for/r_model/r_bind_*/ r_on_*) for React-flavored apps - react-app/: registry + renderer (expression evaluation against the shared state, conditionals, lists, controlled-component models, scoped slots, event modifiers), 14 built-in component ports, vite build into module/react-www - module/react.py + ui/core.py flush branch for the react client type - examples/react/, serializer unit tests, Playwright e2e, react steps in CI, react-www in wheel data

jourdain · 2026-08-28T21:31:21Z

@@ -0,0 +1,2 @@
+/*! coi-serviceworker v0.1.7 - Guido Zuidhof and contributors, licensed under MIT */


That file can be removed. We don't need it anymore. No need to keep it for react

jourdain · 2026-08-28T21:46:52Z

+    return body, arg, []
+
+
+def _apply_directive(dirs, js_key, expr):


Let's remove directives since they are not part of the react logic.

jourdain · 2026-08-28T21:50:26Z

+    if isinstance(elem, str):
+        return {"tag": "__fragment", "children": split_text(elem)}
+
+    server = getattr(elem, "server", None)


If we pass the first if, we should be an abstract element which should have a server even if it is initialized to None...

We could have an explicit is_instance in an assert.

I can be wrong but that code like AI generated with lot of guarding while it should not needed.

jourdain · 2026-08-28T21:51:43Z

+    ("r_model_lazy", "v-model.lazy"),
+    ("r_model_number", "v-model.number"),
+    ("r_model_trim", "v-model.trim"),
+    ("r_slot", "v-slot"),


remove all r_ as it is not part of react logic

jourdain · 2026-08-28T21:53:31Z

        return "\n".join(out_buffer)

+    @property
+    def react_node(self):


should match the AbstractLayout react() property name.

actually since in react they are different. The current name make sense.

jourdain · 2026-08-28T21:56:48Z

            name
            for name in self._py_attr.keys()
-            if name.startswith("v_model_") or name.startswith("v_bind_")
+            if name.startswith(("v_model_", "r_model_", "v_bind_", "r_bind_"))


remove r_*

jourdain · 2026-08-28T21:57:03Z


                # smart key handling
-                if name.startswith("v_model_"):
+                if name.startswith(("v_model_", "r_model_")):


remove r_*

jourdain · 2026-08-28T21:57:08Z

                    else:
                        js_key = f"v-model:{model_name}{'.' if len(modifiers) else ''}{'.'.join(modifiers)}"
-                elif name.startswith("v_bind_"):
+                elif name.startswith(("v_bind_", "r_bind_")):


remove r_*

jourdain · 2026-08-28T22:00:36Z

+        }
        return self

    def attrs(self, *names):


that method should be revisited to better handle vue vs react logic. Having both at the same time is confusing.

jourdain · 2026-08-28T22:01:46Z

            return f"<{self._elem_name} html-error />"

+    @property
+    def react_node(self):


should match the AbstractLayout react() property name.

actually since in react they are different. The current name make sense.

jourdain · 2026-08-28T22:22:17Z

+def to_react_template(root):
+    """Serialize a layout root into the JSON string pushed to the client"""
+    node = root.react_node if hasattr(root, "react_node") else to_react_node(root)
+    return json.dumps({"version": 1, "root": node})


Should not convert to a string... We should keep the native structure as it will speedup network and handling on the client side.

jourdain · 2026-08-28T22:23:02Z

+function parsePayload(payload: unknown): TrameJsonNode | null {
+  if (!payload) return null;
+  try {
+    const { root } = JSON.parse(payload as string) as TrameTemplatePayload;


Should be the native structure rather than a json string

jourdain · 2026-08-28T22:25:08Z

+  stateKey?: string | null;
+}) {
+  const trame = useTrame();
+  useTrameState(); // template-wide re-render on any dirty state


that full re-render is quite bad, I'm wondering if there is no other path that will make it cleaner. Maybe something based on Zustand for state handling?

State key now holds the payload dict directly instead of a pre-serialized JSON string; client keeps a string parse path for backward compatibility. Drop unused coi-serviceworker from the react app.

patrickoleary · 2026-08-31T13:13:17Z

Pushed 89c4008 — review fixes for the native-dict template payload:

trame__template_* now carries the payload dict directly instead of a pre-serialized JSON string (server to_react_template, client extractRoot); client keeps a JSON-string parse path for backward compatibility, and the error payloads (errorPayload) now push the native dict like the vue clients push their native template string.
Fixed boolean v-* flags (r_else=True, v-pre, v-once, ...) being recorded as static attrs instead of directives in AbstractElement.attrs, which broke the r_if/r_else_if/r_else chain in the react renderer.
extractRoot returns null (not undefined) when the payload lacks root.
Removed unused loadScript import and the coi-serviceworker from the react app.

patrickoleary · 2026-08-31T13:22:14Z

The hardest thing for non-web developers is mixing javascript and Python. The 'r_*' directives are not for react developers, they are for non-web developers defining there ui on the Python side. So I push back that the directives are totally appropriate for this user base. look at the following examples. Which of these would be more appropriate for the non-web developers.

"""Same UI written twice: with r_* directives vs without.

Run and compare:
  python directives_vs_plain.py --port 8080
    http://localhost:8080/?ui=directives   (r_* directives, client-side)
    http://localhost:8080/?ui=plain        (python rebuild + JS expressions)
"""

from trame.app import get_server
from trame.ui.html import DivLayout
from trame.widgets import html

server = get_server(client_type="react")
state = server.state

# -----------------------------------------------------------------------------
# Shared state
# -----------------------------------------------------------------------------

state.name = "trame"
state.visible = True
state.mode = "A"
state.items = ["alpha", "beta", "gamma"]
state.value = 50
state.rich = "<b>bold</b> from state"

# -----------------------------------------------------------------------------
# 1. With r_* directives: template is flushed once, everything below reacts
#    on the client without any server round-trip or re-flush.
# -----------------------------------------------------------------------------

with DivLayout(server, template_name="directives"):
    # r_text / r_html
    html.Div(r_text="`Hello ${name}`")
    html.Div(r_html=("rich",))

    # r_show
    html.Div("Toggle me", r_show=("visible",))

    # r_if / r_else_if / r_else
    html.Div("mode is A", r_if="mode === 'A'")
    html.Div("mode is B", r_else_if="mode === 'B'")
    html.Div("mode is something else", r_else=True)

    # r_for
    with html.Ul():
        html.Li("{{ idx }}: {{ item }}", r_for="(item, idx) in items", key="item")

    # r_model (+ modifier variant)
    html.Input(type="text", r_model=("name",))
    html.Input(type="range", min=0, max=100, r_model_number=("value",))
    html.Div("value = {{ value }}")

    # r_bind_<prop> / r_on_<event>_<mods>
    html.Div("hover for tooltip", r_bind_title=("name",))
    html.Button("visible = !visible", r_on_click_stop="visible = !visible")
    html.Button(
        "cycle mode",
        click="mode = mode === 'A' ? 'B' : mode === 'B' ? 'C' : 'A'",
    )

    # r_bind / r_on object forms
    html.Div("bound object", r_bind="{ title: name, id: `item-${mode}` }")
    html.Span("event object", r_on="{ mouseenter: () => { visible = true } }")

# -----------------------------------------------------------------------------
# 2. Without directives: same rendered result, but conditionals and loops are
#    resolved in python, so the layout must be re-flushed on every state
#    change; two-way binding is spelled out as bind + event in JS.
# -----------------------------------------------------------------------------


@state.change("visible", "mode", "items", "name")
def rebuild_plain(**_):
    with DivLayout(server, template_name="plain"):
        # text/html via interpolation and python formatting (frozen at flush)
        html.Div("Hello {{ name }}")
        html.Div(state.rich)  # python injects the markup at build time

        # show via a bound style expression (JS ternary)
        html.Div("Toggle me", style=("visible ? '' : 'display: none'",))

        # if/elif/else resolved in python (requires the re-flush)
        if state.mode == "A":
            html.Div("mode is A")
        elif state.mode == "B":
            html.Div("mode is B")
        else:
            html.Div("mode is something else")

        # for-loop resolved in python (requires the re-flush)
        with html.Ul():
            for idx, item in enumerate(state.items):
                html.Li(f"{idx}: {item}")

        # two-way binding spelled out: bind value + event writing back
        html.Input(type="text", value=("name",), input="name = $event.target.value")
        html.Input(
            type="range",
            min=0,
            max=100,
            value=("value",),
            input="value = Number($event.target.value)",
        )
        html.Div("value = {{ value }}")

        # bind/event without helper prefixes
        html.Div("hover for tooltip", title=("name",))
        html.Button("visible = !visible", click="visible = !visible")
        html.Button(
            "cycle mode",
            click="mode = mode === 'A' ? 'B' : mode === 'B' ? 'C' : 'A'",
        )


rebuild_plain()

# -----------------------------------------------------------------------------
# Start server
# -----------------------------------------------------------------------------

if __name__ == "__main__":
    server.start()```

jourdain reviewed Aug 28, 2026

View reviewed changes

refactor(react): push template as native dict

89c4008

State key now holds the payload dict directly instead of a pre-serialized JSON string; client keeps a string parse path for backward compatibility. Drop unused coi-serviceworker from the react app.

		@@ -0,0 +1,2 @@
		/! coi-serviceworker v0.1.7 - Guido Zuidhof and contributors, licensed under MIT /

		return body, arg, []


		def _apply_directive(dirs, js_key, expr):

Uh oh!

Conversation

patrickoleary commented Aug 28, 2026

Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jourdain Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

patrickoleary commented Aug 31, 2026

Uh oh!

patrickoleary commented Aug 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jourdain Aug 28, 2026 •

edited

Loading