From c585de8e06fc5885b868da6673171983686c97df Mon Sep 17 00:00:00 2001 From: Abhin Rustagi Date: Mon, 13 Jul 2026 14:09:58 +0530 Subject: [PATCH 1/6] fix: add docs for BYO chat library --- .../docs/agent/guides/byo-chat-library.mdx | 101 ++++++++++++++++++ docs/content/docs/agent/meta.json | 3 +- 2 files changed, 103 insertions(+), 1 deletion(-) create mode 100644 docs/content/docs/agent/guides/byo-chat-library.mdx diff --git a/docs/content/docs/agent/guides/byo-chat-library.mdx b/docs/content/docs/agent/guides/byo-chat-library.mdx new file mode 100644 index 000000000..de35b0c64 --- /dev/null +++ b/docs/content/docs/agent/guides/byo-chat-library.mdx @@ -0,0 +1,101 @@ +--- +title: BYO Chat Library +description: Replace the built-in component set with your own design system. OpenUI Cloud prompts, validates, and repairs against your components. +--- + +## With the built-in library + +Out of the box, Generative UI on OpenUI Cloud runs on the built-in chat library that ships in `@openuidev/thesys`: a general-purpose catalog (text, headers, tables, charts, forms, tabs, buttons, …) with renderers included. Your app touches it in exactly two places: + +```tsx +// client: render with the built-in components +import { chatLibrary } from "@openuidev/thesys"; +; +``` + +```ts +// backend: pin the built-in library on every Responses call +instructions: createResponsesInstructions({ instructions: "Optional prose for the model." }); +``` + +OpenUI Cloud owns everything in between: the system prompt, output validation, and automatic repair all target the built-in catalog. You never define components, but you also can't change what the model may emit beyond prose instructions. When your product has its own design system, you migrate. + +## Migrating to your own library + +Three steps. Afterwards, OpenUI Cloud generates the prompt from **your** schema, validates and repairs against **your** catalog (it fully replaces the built-in set), and your renderers draw the result. + +**1. Define the library.** One [`defineComponent`](/docs/openui-lang/defining-components) per component, where your React components live. Prop schemas and descriptions are what the model sees; `id` is a free-form revision tag that shows up in logs: + +```tsx title="src/lib/chat-library.tsx" +import { createLibrary, defineComponent } from "@openuidev/react-lang"; +import { z } from "zod"; +import { Metric, Panel } from "@/components"; + +const MetricDef = defineComponent({ + name: "Metric", + description: "A single KPI stat with an optional trend arrow.", + props: z.object({ + label: z.string(), + value: z.string(), + trend: z.enum(["up", "down"]).optional(), + }), + component: Metric, +}); + +const PanelDef = defineComponent({ + name: "Panel", + description: "Top-level container. Children stack vertically.", + props: z.object({ children: z.array(z.union([MetricDef.ref])) }), + component: Panel, +}); + +export const myLibrary = createLibrary({ + id: "acme-chat@1", + root: "Panel", + components: [PanelDef, MetricDef], +}); +``` + +**2. Generate the spec handover file.** [`openui generate-spec`](/docs/api-reference/cli#openui-generate-spec) turns the library module into a self-contained JSON file for the backend: + +```bash tab="pnpm" tab-group="pkg" +pnpx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json +``` + +```bash tab="bun" tab-group="pkg" +bunx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json +``` + +```bash tab="yarn" tab-group="pkg" +yarn dlx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json +``` + +```bash tab="npm" tab-group="pkg" +npx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json +``` + +**3. Declare it in the backend call.** Import the generated spec. Any backend works, with no React or component code server-side. + +```diff ++ import chatLibrarySpec from "./generated/chat-library-spec.json"; + +- instructions: createResponsesInstructions(), ++ instructions: createResponsesInstructions({ ++ chatLibrary: chatLibrarySpec, ++ systemPromptOptions: { preamble: "You build dashboards for Acme operators." }, ++ }), +``` + +`systemPromptOptions` (only valid alongside `chatLibrary`) tunes the generated prompt: `preamble`, `additionalRules`, `examples`, `toolExamples`, `tools`, `toolCalls`, `bindings`. + +**4. Swap the client library:** + +```diff +- import { chatLibrary } from "@openuidev/thesys"; ++ import { myLibrary } from "@/lib/chat-library"; + +- ; ++ ; +``` + +That's the whole migration. Regenerate the spec (and bump `id`) whenever components change. diff --git a/docs/content/docs/agent/meta.json b/docs/content/docs/agent/meta.json index 08d543204..8782b301d 100644 --- a/docs/content/docs/agent/meta.json +++ b/docs/content/docs/agent/meta.json @@ -24,6 +24,7 @@ "reference/self-hosting", "---Guides---", "guides/custom-artifacts", - "guides/migrating" + "guides/migrating", + "guides/byo-chat-library" ] } From 6dea5e38e2480308ee0f5d5841ad8384fdb6c32d Mon Sep 17 00:00:00 2001 From: Abhin Rustagi Date: Mon, 13 Jul 2026 16:26:54 +0530 Subject: [PATCH 2/6] fix: update fields --- docs/content/docs/agent/guides/byo-chat-library.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/agent/guides/byo-chat-library.mdx b/docs/content/docs/agent/guides/byo-chat-library.mdx index de35b0c64..27064f0f4 100644 --- a/docs/content/docs/agent/guides/byo-chat-library.mdx +++ b/docs/content/docs/agent/guides/byo-chat-library.mdx @@ -86,7 +86,7 @@ npx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generat + }), ``` -`systemPromptOptions` (only valid alongside `chatLibrary`) tunes the generated prompt: `preamble`, `additionalRules`, `examples`, `toolExamples`, `tools`, `toolCalls`, `bindings`. +`systemPromptOptions` (only valid alongside `chatLibrary`) tunes the generated prompt: `preamble`, `additionalRules`, `examples`. **4. Swap the client library:** From 7a840217bb69d44a186fcebc43fc489c77d698f6 Mon Sep 17 00:00:00 2001 From: Abhin Rustagi Date: Tue, 14 Jul 2026 12:21:53 +0530 Subject: [PATCH 3/6] fix: change name --- docs/content/docs/agent/guides/byo-chat-library.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/agent/guides/byo-chat-library.mdx b/docs/content/docs/agent/guides/byo-chat-library.mdx index 27064f0f4..bbc60319d 100644 --- a/docs/content/docs/agent/guides/byo-chat-library.mdx +++ b/docs/content/docs/agent/guides/byo-chat-library.mdx @@ -1,5 +1,5 @@ --- -title: BYO Chat Library +title: OpenUI Cloud: BYO Chat Library description: Replace the built-in component set with your own design system. OpenUI Cloud prompts, validates, and repairs against your components. --- From ac1f8ca2b736328e5fecd6ec8d94bf712fc8c7c5 Mon Sep 17 00:00:00 2001 From: Abhin Rustagi Date: Tue, 14 Jul 2026 14:10:50 +0530 Subject: [PATCH 4/6] fix: update the content & resolve comments --- ...{byo-chat-library.mdx => chat-library.mdx} | 35 +++++++++---------- docs/content/docs/agent/meta.json | 2 +- 2 files changed, 18 insertions(+), 19 deletions(-) rename docs/content/docs/agent/guides/{byo-chat-library.mdx => chat-library.mdx} (58%) diff --git a/docs/content/docs/agent/guides/byo-chat-library.mdx b/docs/content/docs/agent/guides/chat-library.mdx similarity index 58% rename from docs/content/docs/agent/guides/byo-chat-library.mdx rename to docs/content/docs/agent/guides/chat-library.mdx index bbc60319d..b2338854a 100644 --- a/docs/content/docs/agent/guides/byo-chat-library.mdx +++ b/docs/content/docs/agent/guides/chat-library.mdx @@ -1,34 +1,35 @@ --- -title: OpenUI Cloud: BYO Chat Library -description: Replace the built-in component set with your own design system. OpenUI Cloud prompts, validates, and repairs against your components. +title: "OpenUI Cloud: Chat Library" +description: Use OpenUI Cloud with its built-in chat library, or bring your own components. --- -## With the built-in library +## Using the built-in library -Out of the box, Generative UI on OpenUI Cloud runs on the built-in chat library that ships in `@openuidev/thesys`: a general-purpose catalog (text, headers, tables, charts, forms, tabs, buttons, …) with renderers included. Your app touches it in exactly two places: +Out of the box, OpenUI Cloud ships a general-purpose chat library: text, headers, tables, charts, forms, tabs, buttons, and more. The client renders with it: ```tsx -// client: render with the built-in components import { chatLibrary } from "@openuidev/thesys"; + ; ``` +And the backend pins it when building the request instructions: + ```ts -// backend: pin the built-in library on every Responses call -instructions: createResponsesInstructions({ instructions: "Optional prose for the model." }); +instructions: createResponsesInstructions({ instructions: "Optional instructions for the model." }); ``` -OpenUI Cloud owns everything in between: the system prompt, output validation, and automatic repair all target the built-in catalog. You never define components, but you also can't change what the model may emit beyond prose instructions. When your product has its own design system, you migrate. +OpenUI Cloud takes care of everything in between: the system prompt, output validation, and automatic repair all target the built-in library. -## Migrating to your own library +## Using your own library -Three steps. Afterwards, OpenUI Cloud generates the prompt from **your** schema, validates and repairs against **your** catalog (it fully replaces the built-in set), and your renderers draw the result. +There can be multiple reasons to use your library instead of the built-in one like if the domain calls for components the generic set can't express or when the app follows its own design system. To lift it, you can provide your own chat library. The migration is four steps. -**1. Define the library.** One [`defineComponent`](/docs/openui-lang/defining-components) per component, where your React components live. Prop schemas and descriptions are what the model sees; `id` is a free-form revision tag that shows up in logs: +**1. Define the library.** One [`defineComponent`](/docs/openui-lang/defining-components) per component, in the frontend where your React components live. Prop schemas and descriptions are what the model sees; `id` is an optional free-form revision tag: ```tsx title="src/lib/chat-library.tsx" import { createLibrary, defineComponent } from "@openuidev/react-lang"; -import { z } from "zod"; +import { z } from "zod/v4"; import { Metric, Panel } from "@/components"; const MetricDef = defineComponent({ @@ -39,14 +40,14 @@ const MetricDef = defineComponent({ value: z.string(), trend: z.enum(["up", "down"]).optional(), }), - component: Metric, + component: ({ props }) => , }); const PanelDef = defineComponent({ name: "Panel", description: "Top-level container. Children stack vertically.", - props: z.object({ children: z.array(z.union([MetricDef.ref])) }), - component: Panel, + props: z.object({ children: z.array(MetricDef.ref) }), + component: ({ props, renderNode }) => {renderNode(props.children)}, }); export const myLibrary = createLibrary({ @@ -74,7 +75,7 @@ yarn dlx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./ge npx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json ``` -**3. Declare it in the backend call.** Import the generated spec. Any backend works, with no React or component code server-side. +**3. Declare it in the backend call.** Import the generated JSON and pass it as `chatLibrary`. Any TypeScript backend works; no React or component code runs server-side. ```diff + import chatLibrarySpec from "./generated/chat-library-spec.json"; @@ -97,5 +98,3 @@ npx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generat - ; + ; ``` - -That's the whole migration. Regenerate the spec (and bump `id`) whenever components change. diff --git a/docs/content/docs/agent/meta.json b/docs/content/docs/agent/meta.json index 8782b301d..051dc3a4f 100644 --- a/docs/content/docs/agent/meta.json +++ b/docs/content/docs/agent/meta.json @@ -25,6 +25,6 @@ "---Guides---", "guides/custom-artifacts", "guides/migrating", - "guides/byo-chat-library" + "guides/chat-library" ] } From cdfeea84d9145d4746a995afa7ca829ed0191790 Mon Sep 17 00:00:00 2001 From: Abhin Rustagi Date: Tue, 14 Jul 2026 14:13:04 +0530 Subject: [PATCH 5/6] fix: content fix --- docs/content/docs/agent/guides/chat-library.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/content/docs/agent/guides/chat-library.mdx b/docs/content/docs/agent/guides/chat-library.mdx index b2338854a..d0a12c87b 100644 --- a/docs/content/docs/agent/guides/chat-library.mdx +++ b/docs/content/docs/agent/guides/chat-library.mdx @@ -13,10 +13,12 @@ import { chatLibrary } from "@openuidev/thesys"; ; ``` -And the backend pins it when building the request instructions: +And the backend uses it by default when building the request instructions: ```ts -instructions: createResponsesInstructions({ instructions: "Optional instructions for the model." }); +instructions: createResponsesInstructions({ + instructions: "Optional instructions for the model.", +}); ``` OpenUI Cloud takes care of everything in between: the system prompt, output validation, and automatic repair all target the built-in library. From 8646b50b6bfe03e656a02c024c2746913c78f555 Mon Sep 17 00:00:00 2001 From: Abhin Rustagi Date: Tue, 14 Jul 2026 16:23:39 +0530 Subject: [PATCH 6/6] fix: change content --- docs/content/docs/agent/guides/chat-library.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/content/docs/agent/guides/chat-library.mdx b/docs/content/docs/agent/guides/chat-library.mdx index d0a12c87b..55378b029 100644 --- a/docs/content/docs/agent/guides/chat-library.mdx +++ b/docs/content/docs/agent/guides/chat-library.mdx @@ -5,7 +5,7 @@ description: Use OpenUI Cloud with its built-in chat library, or bring your own ## Using the built-in library -Out of the box, OpenUI Cloud ships a general-purpose chat library: text, headers, tables, charts, forms, tabs, buttons, and more. The client renders with it: +Out of the box, OpenUI Cloud ships a general-purpose chat library: text, headers, tables, charts, forms, tabs, buttons, and more. ```tsx import { chatLibrary } from "@openuidev/thesys"; @@ -25,9 +25,9 @@ OpenUI Cloud takes care of everything in between: the system prompt, output vali ## Using your own library -There can be multiple reasons to use your library instead of the built-in one like if the domain calls for components the generic set can't express or when the app follows its own design system. To lift it, you can provide your own chat library. The migration is four steps. +There can be multiple reasons to use your library instead of the built-in one like if the domain calls for components the generic set can't express or when the app follows its own design system. To lift it, you can provide your own chat library. -**1. Define the library.** One [`defineComponent`](/docs/openui-lang/defining-components) per component, in the frontend where your React components live. Prop schemas and descriptions are what the model sees; `id` is an optional free-form revision tag: +**Define the library.** One [`defineComponent`](/docs/openui-lang/defining-components) per component, in the frontend where your React components live. Prop schemas and descriptions are what the model sees; `id` is an optional free-form revision tag: ```tsx title="src/lib/chat-library.tsx" import { createLibrary, defineComponent } from "@openuidev/react-lang"; @@ -59,7 +59,7 @@ export const myLibrary = createLibrary({ }); ``` -**2. Generate the spec handover file.** [`openui generate-spec`](/docs/api-reference/cli#openui-generate-spec) turns the library module into a self-contained JSON file for the backend: +**Generate the spec handover file.** [`openui generate-spec`](/docs/api-reference/cli#openui-generate-spec) turns the library module into a self-contained JSON file for the backend: ```bash tab="pnpm" tab-group="pkg" pnpx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json @@ -77,7 +77,7 @@ yarn dlx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./ge npx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json ``` -**3. Declare it in the backend call.** Import the generated JSON and pass it as `chatLibrary`. Any TypeScript backend works; no React or component code runs server-side. +**Declare it in the backend call.** Import the generated JSON and pass it as `chatLibrary`. ```diff + import chatLibrarySpec from "./generated/chat-library-spec.json"; @@ -91,7 +91,7 @@ npx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generat `systemPromptOptions` (only valid alongside `chatLibrary`) tunes the generated prompt: `preamble`, `additionalRules`, `examples`. -**4. Swap the client library:** +**Swap the client library:** ```diff - import { chatLibrary } from "@openuidev/thesys";