PSA/ee/docs/extension-system/template-system-guide.md

Client UI SDK Guide (Iframe)

This guide explains how iframe apps interact with the host via the Extension Iframe SDK and how to build consistent UIs with the UI kit.

Packages

• @alga/extension-iframe-sdk — handshake, auth, navigation, theme, telemetry
• @alga/ui-kit — accessible components, design tokens, hooks

Getting Started

import { BridgeProvider, useExtension } from '@alga/extension-iframe-sdk';
import { Button, DataTable } from '@alga/ui-kit';

function App() {
  const { context } = useExtension(); // { extensionId, authHeaders, gatewayBase, theme }

  async function sync() {
    await fetch(`${context.gatewayBase}/api/ext/${context.extensionId}/agreements/sync`, {
      method: 'POST',
      headers: { ...context.authHeaders, 'content-type': 'application/json' },
      body: JSON.stringify({ force: true })
    });
  }

  return <Button onClick={sync}>Sync</Button>;
}

export default function Root() {
  return (
    <BridgeProvider>
      <App />
    </BridgeProvider>
  );
}

Auth & Requests

• Use context.authHeaders for gateway calls; do not forward end‑user tokens
• Always call /api/ext/${extensionId}/... paths (the Gateway proxies to Runner POST /v1/execute)
• Gateway reference: server/src/app/api/ext/[extensionId]/[[...path]]/route.ts

Navigation

• Prefer host‑managed navigation events when integrated in larger flows
• SDK exposes helpers to request navigation changes from the host (implementation detail subject to SDK version)

Theme

• UI kit consumes CSS variables provided by the host
• The bridge emits theme updates; subscribe if your app needs to react dynamically

Telemetry & Logging

• Use SDK/Host APIs to emit telemetry and structured logs rather than console.* for operational visibility

Security Notes

• Do not evaluate code at runtime (no template engines)
• Avoid cross‑origin requests; route everything via the gateway
• UI assets are served by the Runner at ${RUNNER_PUBLIC_BASE}/ext-ui/{extensionId}/{content_hash}/[...]; the Next.js ext-ui route gates/redirects when rust-host mode is enabled.
• Iframe src is constructed by buildExtUiSrc() and bootstrapped via bootstrapIframe()

See also: DataTable Integration Guide, Manifest v2, and API Routing Guide.