This document describes the concept behind
@ui5-community/jsx-runtime. For the requirements spec see requirements.md. For a hands-on demo, runpnpm devat the repo root and browse the showcase.
The @ui5-community/jsx-runtime package is a small, purpose-built JSX runtime that lets you write UI5 views as .tsx files:
import View from "sap/ui/core/mvc/View";
import Button from "sap/m/Button";
export default class Hello extends View {
createContent() {
return <Button text="Hi" press=".onTap" />;
}
}There is no React, no virtual DOM, and no reconciler. JSX expressions compile to plain new Control(settings) calls. The runtime exists to glue Babel's automatic-runtime output into UI5's existing settings/binding/event model, and to expose a stable plugin contract on top.
With ui5-tooling-transpile (≥ 3.12) you don't hand-author a Babel config — enable the JSX transform (@babel/plugin-transform-react-jsx, v7; the v8 major breaks the transform) with a transformJSX option in ui5.yaml and point importSource at the library:
customConfiguration:
config-ui5-tooling-transpile: &cfgTranspile
transformJSX:
runtime: automatic
importSource: "ui5/community/jsx/runtime"The tooling then runs Babel, which emits, at the top of every .tsx file:
import { jsx as _jsx, jsxs as _jsxs } from "ui5/community/jsx/runtime/jsx-runtime";The /jsx-runtime suffix is hard-coded by the transform, the library exposes exactly this path.
| Layer | What it is | Who uses it |
|---|---|---|
Core: jsx, jsxs, Fragment, <For>, <If> |
The directives that ship with every TSX app. Always available, no setup. | Every view author. |
Plugin SPI: withScope, defineSentinel, the four extension-point types |
The contract for adding directives, intrinsics, output adapters, etc. without touching the core. | Plugin authors. |
Sample plugin: <Switch>/<Case>/<Default> from @ui5-community/jsx-runtime/plugins/switch |
The M3-style non-trivial example. | Anyone who wants a template for their own plugin. |
If you only write views, skip to the Core directives section below. The plugin SPI exists so the runtime can grow without growing the core; you do not need to learn it to write apps.
Walk through what happens when Babel transforms
<Page>
<Button press=".onTap" text="Hello" />
</Page>-
Babel emits
_jsx(Page, { children: _jsx(Button, { press: ".onTap", text: "Hello" }) });
-
The inner
_jsx(Button, props)calls the library'sjsxfunction:- Looks up
Button.getMetadata(). UI5's standard metadata API. - Walks
props. Thepressvalue is the string".onTap", and a core intrinsic handler (the dot-handler) claims it becausemetadata.hasEvent("press")returns true. The handler installs a real function that, at fire-time, walks up the element tree, finds the surrounding view's controller, and callscontroller.onTap(event). textis just forwarded as-is.- The active
Rendereris asked to construct the result. The default control-instance renderer returnsnew Button({ press: realHandler, text: "Hello" }).
- Looks up
-
The outer
_jsx(Page, ...)callsjsx(Page, props):props.childrenis the Button instance. It's stripped and the runtime looks upPage's default aggregation (content).- Settings become
{ content: button }. - Result:
new Page({ content: button }).
UI5 does the rest, applySettings wires up bindings, ManagedObject takes care of aggregations, the renderer walks the tree.
Any prop value that is a plain object with a path field is treated by UI5 as a BindingInfo, literal { path: "/X", model: "m" } works fine. Both the runtime's own intrinsic parsing and UI5's applySettings will treat it identically.
<Table items={listRef}> sets items to a BindingInfo. The JSX child, typically a <ColumnListItem>, is normally appended to the default aggregation, but when the default aggregation already holds a BindingInfo the runtime installs the child as that binding's template instead. UI5's GrowingEnablement then clones the template per row. The <For> directive below is sugar over this pattern.
The directives in this section are always available, with no setup. They are core ChildrenProcessors registered into the default scope at module load.
<>...</> compiles to _jsx(Fragment, { children: [...] }). The runtime recognises the Fragment sentinel and inlines its children into the parent aggregation. The same helper drops null, undefined, false, and "" so JSX patterns like {flag && <X/>} Just Work, no aggregation crashes.
Sugar over the "bound items + JSX child = template" pattern. The each prop carries a binding info, a literal { path: "/items" }. The render-prop's return value becomes the row template. Compiles to:
<List>
<For each={{ path: "/items" }}>{() => (
<StandardListItem title="{label}" description="ID: {id}" />
)}</For>
</List>
// → new List({ items: { path: "/items", template: new StandardListItem({...}) } })Templates use relative paths ("{label}", no leading slash) because UI5 resolves per-row properties via the row's binding context. Default target is the parent's default aggregation; pass aggregation="cells" to override.
Two modes, picked by the type of condition:
- Literal (
true/false): children are inlined or omitted at construction, no wrapper. - Bound (any object with a
pathfield): the runtime callschild.bindProperty("visible", cond)on every child directly. No wrapper control, no extra DOM node, nosap.m(or any other library) dependency,bindPropertyis onManagedObject.
If a child already binds its own visible (or pins it to false), <If> throws. Combine the conditions in an expression binding (visible={{= ${outer} && ${inner} }}) or write a wrapper layout for that case.
Two ways to wire a handler:
<Button press=".onTap" /> // string starting with "."
<Button press={(ev) => /* ... */} /> // direct functionThe string form mirrors XML-view notation. The runtime resolves the method on the surrounding view's controller at fire-time via a parent-walk (or against a pinned controller if one was set via withScope({ controller }, fn)).
You only need this section if you are writing a plugin.
Five extension points, each with a single responsibility, none mandatory:
| Extension point | Purpose |
|---|---|
Renderer |
What jsx() produces from (type, settings). Default = new type(settings). |
IntrinsicHandler |
Pre-construction attribute pre-processing (class=, binding=, ref=, dot-handler events). |
PropertyApplier |
Post-construction property semantics (e.g. promise-valued props). |
ChildrenProcessor |
Structural-directive extension (<For>, <If>, <Fragment>, plus plugin sentinels). |
Scope + withScope |
Stack-saved context that holds the four registries. |
The core's own class=, dot-handler events, binding="{/X}", ref={cb}, <Fragment>, <For>, and <If> are all implemented as defaults registered into the default scope at module load, which means a plugin that wants to override one of them does so the same way it adds a new one. Nothing in the core is privileged.
import { withScope } from "@ui5-community/jsx-runtime";
import { switchProcessor, Switch, Case, Default } from "@ui5-community/jsx-runtime/plugins/switch";
createContent() {
return withScope({ childrenProcessors: [switchProcessor] }, () => (
<VBox>
<Switch on={kind}>
<Case when="info"><Title text="Info" /></Case>
<Default> <Title text="—" /></Default>
</Switch>
</VBox>
));
}withScope is synchronous: it pushes a merged scope on entry and restores the parent on fn's synchronous return and on exception. An await inside the callback would leak the scope across the boundary, plugins that need scope-with-await must wrap their own withAsyncScope around an AsyncLocalStorage.
import {
defineSentinel,
isSentinelNode,
type ChildrenProcessor
} from "@ui5-community/jsx-runtime";
export const Comment = defineSentinel<{ children?: unknown }>("Comment");
export const commentProcessor: ChildrenProcessor = {
matches: (child) => isSentinelNode(child) && child.tag === Comment,
process: () => { /* drop everything inside */ }
};The plugin imports four symbols from the runtime SPI. That is the entire surface a plugin author has to learn.
- The core never imports
sap.m/sap.f/sap.tnt/sap.fe. Every library- or framework-specific feature is a plugin. - Every plugin is independently retirable. Deleting the folder leaves the runtime unchanged.
withScoperestores on synchronous return and on exception. Concurrent JSX calls are safe because each opens its own scope.- Sentinel directives are JSX-typed.
defineSentinel<P>(name)propagatesPthroughLibraryManagedAttributes, so<Switch on={...}>...</Switch>is checked at compile time the same way<Button text={...}/>is.
JSX.Element = any. JSX expressions are typed asanyso they can satisfy any concrete named-aggregation slot. Per-prop validation is unaffected; it flows throughLibraryManagedAttributes(below), which keeps the strong per-control typing. This is the same trade-off React makes via the opaqueReact.ReactElement.LibraryManagedAttributes<C, _P>extracts the$XSettingsinterface from each control's constructor viaConstructorParametersinference.@openui5/typesalready publishes those interfaces, generated from each control's metadata, so the runtime gets per-control typing for properties, named aggregations, associations, and event payloads with no codegen step in this repo.
- Async
createContent. If you read a class field insidecreateContent, defer JSX construction withPromise.resolve().then(...).super()runscreateContent()before class field initializers. withScopeis synchronous. Don'tawaitinside the callback.- Plugin sentinels need their scope. A
<Switch>outside awithScope({ childrenProcessors: [switchProcessor] }, …)call will throw from the sentinel's call body.