Declarative UI

The hello-tree template lets you build complete extension UIs without any executable code. The UI is defined as a JSON tree of @oxprotocol/ui components. This is the safest possible extension type — no JS, no Wasm, no attack surface beyond the tree data.

Create a Declarative Extension

oxp create -t hello-tree my-tree-ext
cd my-tree-ext

The Tree File

Instead of ui/index.html, a hello-tree extension has a ui/tree.json:

{
  "kind": "stack",
  "gap": 3,
  "children": [
    { "kind": "text", "value": "Hello from OXP", "variant": "heading" },
    { "kind": "text", "value": "This entire UI is declarative JSON. No code." },
    {
      "kind": "stack",
      "axis": "horizontal",
      "gap": 2,
      "children": [
        { "kind": "button", "label": "Action A", "action": "a", "variant": "primary" },
        { "kind": "button", "label": "Action B", "action": "b", "variant": "secondary" }
      ]
    },
    {
      "kind": "code",
      "value": "console.log('rendered by the host');",
      "language": "js"
    }
  ]
}

Security Guarantees

Declarative ui-v1 bundles are validated by assertBundlePolicy at both CLI pack time and registry upload:

• **No .js, .mjs, .cjs, .jsx, .ts, .tsx files allowed**
• **No .wasm, .sh, .exe, .dll, .so, .dylib files allowed**
• **The JSON tree is validated against the oxp-ui-v1 schema**

This makes ui-v1 extensions safe to install from any publisher — there is no code execution path.

When to Use Declarative UI

Use declarative UI when:

• Your extension displays static or configuration-driven content
• You want maximum trust from users (no code = no risk)
• The UI is simple enough to express as a component tree
• You want the fastest possible install (no Wasm compilation)

Move to component-v1 (Rust) when you need:

• Dynamic data from APIs
• Complex state management
• File system operations
• Custom business logic