Conversational UI framework. Build agent interfaces with JSX.
Operations declare what the agent sees with <Brief> — the framework renders it differently per target (ChatGPT Apps SDK, LLM tool results, in-app chat, and the deprecated GPT Store).
bunx create-donghanh my-app
cd my-app
bun install
bun run dev/** @jsxImportSource @donghanh/core */
import { Action, Brief, Display, registerOperation } from "@donghanh/core";
function ListItems({ data }) {
return (
<Brief>
{`You have ${data.items.length} items.`}
<Display data={data.items} />
<Action operation="add-item" label="Add an item" />
</Brief>
);
}
export default registerOperation(ListItems, {
id: "list-items",
type: "query",
description: "List all items",
instruction: "Call this to see all items.",
input: {},
responseKey: "listItems",
auth: "required", // "none" | "optional" | "required"
widget: "items", // optional — binds to an Apps SDK widget
});The <Brief> is the agent's HUD — not shown to users. The framework renders it differently per target:
| Target | Adapter | <Message> |
<Action> |
<Display> |
|---|---|---|---|---|
| ChatGPT GPT Store (deprecated) | gptRoutes |
nextSteps |
suggestedActions[] |
display field |
| ChatGPT Apps SDK (MCP) | mcpRoutes + @donghanh/widget |
content[] text |
structuredContent.actions → iframe buttons |
structuredContent.display → iframe |
| Self-hosted React chat | chatRoutes + @donghanh/react |
tool-result text | action metadata | formatted text |
| Package | Description |
|---|---|
@donghanh/core |
Custom JSX runtime, primitives, registry, executor |
@donghanh/hono |
Hono routes: gptRoutes (GPT Store, deprecated), mcpRoutes (Apps SDK), chatRoutes (LLM chat) |
@donghanh/react |
Headless React hooks for self-hosted chat (useChat, useInitOperation) |
@donghanh/widget |
Iframe runtime for Apps SDK widgets — MCP bridge, hooks, renderers |
@donghanh/widget-vite |
Vite plugin that bundles widgets into inline HTML + manifest for mcpRoutes |
create-donghanh |
CLI scaffolding tool |
bunx create-donghanh my-app --template minimal # 2 operations, D1 SQLite
bunx create-donghanh my-app --template kanban-gpt # 6 operations, OAuth, Better AuthBy default every operation is an MCP tool. For apps with many operations, mcpRoutes takes exposure to keep a few as tools and put the rest in a catalog behind find_operations, get_operation, run_read, run_write and run_destructive:
mcpRoutes({ /* ... */ exposure: { default: "tool", catalog: { type: "query" }, pin: ["start"] } });App({ operations, instructions }) carries the app's playbook; every adapter uses it (initialize.instructions for MCP). @donghanh/core/skills adds searchable skills and @donghanh/core/files gives the agent paged, searchable access to the files in them and in your docs. See the docs site for details.
your-app/
├── operations/ # One .tsx file per operation
│ ├── list-items.tsx # Returns <Brief> with actions + display
│ └── index.ts # Registry (as const)
├── executor.ts # Maps operation IDs → data fetching
└── worker.ts # Hono entry, mounts routes
Executor is injected — the framework doesn't care about your data source. Use D1 SQLite, Turso, Postgres, REST APIs, or anything else.
Operations are components — each .tsx file receives { data, variables } and returns a <Brief>. Metadata is attached via registerOperation().
Deprecated: GPT Store support is deprecated. Use Apps SDK (
mcpRoutes) for new projects.gptRouteskeeps working.
Each operation declares an auth posture. gptRoutes enforces it per-op and exposes a dedicated /public sub-path for ops that don't require auth:
auth value |
Default route behavior | /public route behavior |
|---|---|---|
"required" (default) |
authenticate() → 401 on failure |
404 — not exposed |
"optional" |
authenticate() on failure → anonymous |
200 anonymous (swallows bad tokens) |
"none" |
Skip authenticate() → anonymous |
200 anonymous |
// A public op — callable by anyone, inside or outside ChatGPT OAuth
registerOperation(CheckOffer, {
id: "check-offer",
type: "query",
auth: "none",
// ...
});
// Request either:
// GET /api/gpt/query/check-offer → 200 anonymous
// GET /api/gpt/public/query/check-offer → 200 anonymous (OAS-friendly, no Bearer needed)For ChatGPT Actions in particular: point the Action's path at /public/... when you want a guest-callable endpoint, and at the default path when you want the auth-required variant. This sidesteps OpenAPI's all-or-nothing per-path security model.
Generate an OpenAPI 3.1 document from your registry — no hand-maintained JSON:
import { generateOpenApi } from "@donghanh/hono";
app.get("/openapi.json", (c) =>
c.json(
generateOpenApi({
registry,
info: { title: "My API", version: "1.0.0" },
servers: [{ url: "https://api.example.com" }],
basePath: "/api/gpt",
}),
),
);Each op gets a concrete path based on its auth posture. Upload the JSON (or paste the URL) in the GPT Actions editor.
Tán Đồng — bill-splitting app built with @donghanh. 14 operations, GPT Store integration, in-app chat assistant.
See CONTRIBUTING.md for setup, how to make and document a change, versioning and releases.
MIT