Skip to content

The Open Standard for Generative UI

Docs: BYO Chat Library (#756)

ABf7d0f0aa13b3
diff --git a/packages/openui-cli/src/templates/openui-cloud/README.md b/packages/openui-cli/src/templates/openui-cloud/README.md
index 3b0d1d334..c12785790 100644
--- a/packages/openui-cli/src/templates/openui-cloud/README.md
+++ b/packages/openui-cli/src/templates/openui-cloud/README.md
@@ -49,7 +49,7 @@ OPENUI_MODEL=google/gemini-3.6-flash-free
## SDK packages
- `@openuidev/thesys-server` — the server SDK (`artifactTool`,
- `createResponsesInstructions`) used by the `/api/chat` route.
+ `generateSystemPrompt`) used by the `/api/chat` route.
- `@openuidev/thesys` — the React component library (`chatLibrary`, `Presentation`,
`Report`) used by the client page and artifact renderers.
- `@openuidev/react-headless` / `@openuidev/react-ui` — the chat UI runtime
diff --git a/skills/openui/SKILL.md b/skills/openui/SKILL.md
index 5457efe6d..e998ab882 100644
--- a/skills/openui/SKILL.md
+++ b/skills/openui/SKILL.md
@@ -31,9 +31,9 @@ Do not use this skill for general React UI questions, generic design system advi
| `@openuidev/react-headless` | Bring-your-own React chat state, hooks, storage/LLM adapter primitives, streaming adapters, message converters, and artifact primitives without OpenUI's visual components |
| `@openuidev/react-email` | React Email component library and prompt options for generated email |
| `@openuidev/browser-bundle` | CDN/iframe/no-build React renderer bundle exposed as `window.__OpenUI` |
-| `@openuidev/cli` | `openui create` scaffolding and `openui generate` prompt/schema generation from a library export |
+| `@openuidev/cli` | `openui create` scaffolding and `openui generate` system prompt + library spec generation from a library export |
| `@openuidev/thesys` | Version-sensitive client-side OpenUI Cloud helpers such as `useOpenuiCloudStorage()`, Cloud component sets, and Cloud artifact components/renderers/categories; verify current exports |
-| `@openuidev/thesys-server` | Version-sensitive server-side OpenUI Cloud helpers such as `artifactTool` and `createResponsesInstructions` for Cloud-backed `/api/chat` routes |
+| `@openuidev/thesys-server` | Version-sensitive server-side OpenUI Cloud helpers such as `artifactTool` and `generateSystemPrompt` (`createResponsesInstructions` is its deprecated alias) for Cloud-backed `/api/chat` routes |
Choose the package for the target runtime. For backend-only parsing or prompt/schema generation, prefer `@openuidev/lang-core` or the CLI instead of pulling in a UI framework.
@@ -117,7 +117,7 @@ Version-sensitive: verify exact Cloud template env vars, `@openuidev/thesys*` ex
- Store `THESYS_API_KEY` server-side only, typically in `.env.local`.
- The Cloud CLI template also uses `OPENUI_MODEL` in `provider/model` form and `DEMO_USER_ID` for the demo user identity.
- Keep Cloud calls behind server routes such as `/api/chat` and `/api/frontend-token`; never expose the server key to the browser.
-- In the `openui-cloud` template, `/api/chat` uses `@openuidev/thesys-server` helpers such as `artifactTool` and `createResponsesInstructions`.
+- In the `openui-cloud` template, `/api/chat` uses `@openuidev/thesys-server` helpers such as `artifactTool` and `generateSystemPrompt`.
- `AgentInterface` connects to Cloud with `llm` and `storage` props. `llm` points to an app route that proxies Cloud's Responses endpoint, usually with `openAIResponsesAdapter()` and `openAIConversationMessageFormat`. `storage` uses `useOpenuiCloudStorage()` from `@openuidev/thesys` with a short-lived frontend token.
- Cloud-provided component sets, artifact renderers, and categories come from `@openuidev/thesys`.
- Generate keys in the Thesys console: `https://console.thesys.dev/keys`.
@@ -233,11 +233,25 @@ OpenUI publishes first-party examples at `https://github.com/thesysdev/openui/tr
- Third-party UI/component examples: `material-ui-chat`, `shadcn-chat`, `form-generator`, `hands-on-table-chat`.
- Harnesses: `harnesses/pi-agent-harness`, `harnesses/vercel-eve`.
-### Generate a prompt or schema
+### Generate the system prompt and library spec
```bash
+# Default: writes the prompt to --out AND the serialized library spec alongside it (<file>.spec.json)
npx @openuidev/cli@latest generate ./src/library.tsx --out ./src/generated/system-prompt.txt
-npx @openuidev/cli@latest generate ./src/library.tsx --json-schema --out ./src/generated/component-spec.json
+# Spec only (preferred input for backend prompt compilation)
+npx @openuidev/cli@latest generate --spec ./src/library.tsx --out ./src/generated/library.spec.json
+```
+
+Prefer the spec-first pattern in backend routes: generate the spec at build time, then compile the prompt at runtime with `generateSystemPrompt` from `@openuidev/lang-core` (no React dependency):
+
+```ts
+import { generateSystemPrompt, type LibrarySpec } from "@openuidev/lang-core";
+import librarySpec from "./generated/library.spec.json";
+
+const systemPrompt = generateSystemPrompt({
+ library: librarySpec as LibrarySpec,
+ promptOptions: { /* preamble, examples, tools, additionalRules, ... */ },
+});
```
The target module must export a library with `prompt()` and `toJSONSchema()`. By default the CLI looks for `library`, then `default`, then any matching export. It can also auto-detect prompt options from `promptOptions`, `options`, or an export ending in `PromptOptions`.
diff --git a/skills/openui/references/cloud-integration.md b/skills/openui/references/cloud-integration.md
index 891c7802e..044b60f0e 100644
--- a/skills/openui/references/cloud-integration.md
+++ b/skills/openui/references/cloud-integration.md
@@ -256,7 +256,7 @@ of weakening the check.
import { getAuthenticatedUserId } from "@/lib/auth.server";
import { parseCloudChatRequest } from "@/lib/cloud-request";
import { userOwnsCloudConversation } from "@/lib/conversation-ownership.server";
-import { artifactTool, createResponsesInstructions } from "@openuidev/thesys-server";
+import { artifactTool, generateSystemPrompt } from "@openuidev/thesys-server";
import OpenAI from "openai";
export async function POST(req: Request) {
@@ -306,7 +306,7 @@ export async function POST(req: Request) {
stream: true,
store: true,
tools: [artifactTool({ artifacts: ["slides", "report"] })],
- instructions: createResponsesInstructions(),
+ instructions: generateSystemPrompt(),
// The Cloud artifact tool extends the stock OpenAI Responses tool union.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any,
diff --git a/skills/openui/references/oss-to-cloud-migration.md b/skills/openui/references/oss-to-cloud-migration.md
index aecac8240..fb81c48f9 100644
--- a/skills/openui/references/oss-to-cloud-migration.md
+++ b/skills/openui/references/oss-to-cloud-migration.md
@@ -52,7 +52,7 @@ artifacts, custom slots/theme, and tests.
| `openAIMessageFormat` | `openAIConversationMessageFormat` |
| In-memory, `restStorage`, or custom `ChatStorage` | `useOpenuiCloudStorage({ token: "/api/frontend-token" })` |
| `openuiLibrary`/`openuiChatLibrary` | `chatLibrary` from `@openuidev/thesys` when the user chooses Cloud components |
-| `library.prompt(...)` in the provider route | `createResponsesInstructions()` in the Cloud route |
+| `generateSystemPrompt({ library, promptOptions })` in the provider route | `generateSystemPrompt()` from `@openuidev/thesys-server` in the Cloud route |
| App-owned artifact loop/renderers | Managed `artifactTool({ artifacts: ["slides", "report"] })` plus managed renderers for stock artifacts |
| No browser storage credential | Short-lived frontend token scoped to the authenticated `user_id` |
@@ -72,7 +72,7 @@ Preserve branding, theme, starters, slots, navigation, route placement, error bo
8. Remove provider dependencies, environment variables, storage routes, and dead adapters only when no other application path uses them.
9. Update environment examples and deployment configuration without committing secrets.
-Do not send both full history and a Cloud conversation id. Doing so can duplicate context. Do not leave `library.prompt()` in the stock Cloud route; `createResponsesInstructions()` supplies the managed instructions.
+Do not send both full history and a Cloud conversation id. Doing so can duplicate context. Do not leave `library.prompt()` in the stock Cloud route; `generatePromptOptions()` supplies the managed instructions.
## Handle Renderer-Only and Custom-Library Apps