Migrate to Workflow-Owned UIs

Workflow UIs are now declared by the workflow itself with <UI>. The UI still runs in the browser, talks to the Gateway through gateway-react, and can keep the same .smithers/ui/<workflow>.tsx file: only ownership changes. The workflow TSX names the UI entry, so any Gateway that registers the workflow serves the right UI without out-of-band launcher code.

Before

Older launchers mounted UI from the Gateway side:

.smithers/gateway.ts

gateway.register("release", releaseWorkflow, {
  ui: {
    entry: ".smithers/ui/release.tsx",
    title: "Release",
  },
  entryFile: ".smithers/workflows/release.tsx",
});

The old pack convention auto-mounted a matching .smithers/ui/release.tsx file; an explicit workflow declaration replaces it.

After

Add <UI> inside the workflow’s root <Workflow>:

.smithers/workflows/release.tsx

/** @jsxImportSource smthrs */
import { createSmithers, UI } from "smthrs";

const { Workflow, Task, smithers } = createSmithers({
  // schemas...
});

export default smithers((ctx) => (
  <Workflow name="release">
    <UI entry="../ui/release.tsx" title="Release" />
    <Task id="ship">{/* normal workflow work */}</Task>
  </Workflow>
));

Then register the workflow without a ui option:

.smithers/gateway.ts

gateway.register("release", releaseWorkflow, {
  entryFile: ".smithers/workflows/release.tsx",
});

entry paths resolve relative to the workflow file when entryFile is provided; existing self-mounting UI files ending in createGatewayReactRoot(<App />) can stay as-is.

Entry vs Source

Use entry for existing Gateway UI files:

<UI entry="../ui/release.tsx" title="Release" />

Use source for a browser-safe module that exports a React component; the Gateway mounts it with React and passes props plus boot metadata:

<UI
  source="../ui/release-app.tsx"
  exportName="ReleaseApp"
  title="Release"
  props={{ mode: "operator" }}
/>

Don’t point source at the workflow module itself: it often imports Node/Bun APIs, agents, prompts, and database setup that can’t run in the browser.

Checklist

Add UI to the workflow’s smthrs import.
Add <UI entry="../ui/<workflow>.tsx" title="..." /> as a direct child of the root <Workflow>.
Remove ui: { entry, title } from gateway.register; keep entryFile.
Leave the browser UI file in .smithers/ui/<workflow>.tsx unless converting it to the source component-export shape.
Verify with bunx smthrs gateway and open /workflows/<workflow> or run bunx smthrs ui RUN_ID.

The Gateway discovers <UI> during register(); the component renders nothing into the workflow graph and never executes client code on the backend.

Start

Articles

Learn

Capabilities

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

Migrate to Workflow-Owned UIs

Before

After

Entry vs Source

Checklist

​Before

​After

​Entry vs Source

​Checklist

Before

After

Entry vs Source

Checklist