Skip to main content
Deduplicate the assistant-ui singletons react, react-dom, @assistant-ui/core, @assistant-ui/react, and @assistant-ui/store must each resolve to exactly one copy in your bundle. Two copies produce a runtime error along the lines of “requires an AuiProvider”.
The vite.config.ts approach is usually enough. Reach for resolutions (or overrides on npm, pnpm.overrides on pnpm) when a transitive dependency drags in a second copy.Note that @assistant-ui/store arrives transitively through @assistant-ui/core rather than being declared by the SDK, so there is no published version to look up — pin it to whatever your lockfile resolves @assistant-ui/core against.
The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a “blank” first install.
The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a “blank” first install.
Check that @import "@truefoundry/trueforge-ui/styles.css"; is actually reaching the browser — that single import is the entire styling setup, and the stylesheet is self-contained. You do not need Tailwind in your own app for the SDK to look right.
The SDK’s stylesheet deliberately omits Tailwind preflight so it cannot reset your styles, so this is unlikely to come from the import itself. Look instead at whether you added @import "tailwindcss"; at the same time — that one does ship preflight, and it resets host styles by design.
The built-in server failed to resolve. For type: "trueforge", confirm @truefoundry/trueforge-sdk is installed, baseUrl is reachable, and you passed either token or a working fetch — see Quickstart. Attach an onError handler to see the underlying error.
Without an explicit defaultAgentSpec, drafts default to openai-main/gpt-4.1. Pass a spec naming a model your backend actually exposes: agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "..." } } }}.
It seeds a new draft rather than binding to the current one, so the change lands on the next new chat. Clear chat will not pick it up — that path preserves the spec already bound to the draft. To apply it to the conversation on screen, remount the component with a new key. It is ignored entirely in SingleAgent mode.
Settings render only when your server exposes a catalog, so attach one to enable the panel. If you are on a custom layout, that is the other cause — the panel ships with the built-in layouts only.
A screenType=mcp-auth query parameter is present on the URL. TrueForgeUI renders the OAuth completion screen exclusively in that case. Keep the callback on its own route; see MCP OAuth.
The provider toggles the dark class on document.documentElement. Pass a controlled theme.mode derived from your own state so the two stay aligned.
A few names are published as types only, so importing them as values fails. AskUserPrompt, McpAuthPrompt, and ReasoningCard are override-only — supply your own component typed with the published props. Button / IconButton are public values restyled through theme tokens, not slot overrides.
The package is ESM-only and client-only. Mount TrueForgeUI from a client component — in Next.js App Router, a file with "use client" at the top.