* feat(ui): add typed headless createUI adapters
* docs(ui): document typed props, context, and interrupt placement
Teach ToolProps, RegisteredInterruptProps, and UI.useChat. Show tool approvals inline in the tool or in the interrupt list. Put registered generic interrupts under interrupts.generic next to fallback. Unbound interrupts use fallback. Check interrupt.kind when the copy must differ.
* feat(ui): pin InterruptProps and add the typed chatbot example
InterruptProps takes a tool name or a registered interrupt id. A tool approval renders in the tool when interrupts.tools omits that name. examples/ts-react-ui-chatbot shows parts, list vs in-tool approval, BYOK, and transcription.
* fix(ui): export createChatUI and type-check Vue and Svelte examples
Rename the factory to createChatUI. Register every guitar tool in the Vue and Svelte examples so defineComponents type-checks. Point the UI docs at gpt-5.6 and @tanstack/ai-svelte-ui 0.2.0.
* feat(ui): move createChatUI onto framework /ui subpaths
Chat UI now lives at @tanstack/ai-react/ui, @tanstack/ai-solid/ui,
@tanstack/ai-vue/ui, and @tanstack/ai-svelte/ui.
The published @tanstack/ai-react-ui, @tanstack/ai-solid-ui, and
@tanstack/ai-vue-ui packages re-export those subpaths until 1.0.0.
@tanstack/ai-svelte-ui was never published, so that package is gone.
* feat(ui): add createChatHook and move Chat UI onto /ui (#1275)
* feat(ui): add createChatHook and move Chat UI onto /ui (#1263)
* feat(client): add createChatHook bound useChat factory
* feat(ui): align createChatUI with Form and Table factories
* feat(ui): move chat UI onto framework /ui subpaths
Fold the *-ui packages into @tanstack/ai-react/ui, @tanstack/ai-solid/ui, @tanstack/ai-vue/ui, and @tanstack/ai-svelte/ui.
createChatHook({ options, chatComponents }) returns useAppChat (Svelte: createAppChat). useAppChat mixes AppChat onto the instance so screens render <chat.AppChat />.
* ci: apply automated fixes
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
* feat(ui): deprecate ai-*-ui packages in favor of /ui
Restore @tanstack/ai-react-ui, ai-solid-ui, ai-vue-ui, and ai-svelte-ui as
thin re-exports of the framework /ui subpath until 1.0.0.
Document createChatHook, chat.AppChat, and the import path change.
* ci: apply automated fixes
* chore(ui): drop unpublished @tanstack/ai-svelte-ui
That package never shipped on npm. Svelte chat UI lives on
@tanstack/ai-svelte/ui. Keep deprecated shims only for the
published react, solid, and vue UI packages.
* ci: apply automated fixes
* fix(ui): green up the CI suite for createChatHook
Nine tasks were failing on this branch. Fixes, in order of substance:
- `ai-vue`/`ai-solid` ship their `/ui` subpath as source (Vue SFCs and
Solid JSX must be compiled by the consumer), so `create-ui` is
type-checked against the *consumer's* tsconfig. Both referenced a bare
`process`, which broke any consumer without `@types/node` (this is what
failed `ts-vue-chat`). Declare `process` locally, matching the
`src/env.d.ts` shape the devtools packages already use, so the literal
`process.env.NODE_ENV` bundlers substitute stays intact and the branch
is still constant-folded in production.
- `ts-react-ui-chatbot` imported `useChatContext` from `@/chat/ui-context`,
which only exports the raw contexts. It comes off the factory in
`./ui-components`, the way `layout.tsx` already imports it.
- Docs: `docs/ui/react.md`'s widget-picking snippet referenced `UI` and
`message` that no fence defined, and `p.getWeather` for a widget the
example factory never registered. Grouped it with the factory fence and
registered `getWeather`/`text`, so the snippet now type-checks against
the real API instead of only looking right.
- Docs: `docs/ui/vue.md`'s `StatusLine` and `ui` formed an inference cycle.
Declare `StatusLine` after `ui` and annotate it; `h(StatusLine)` only
runs at render time, so the runtime order is unchanged.
- Split the mixed value/type imports in `ai-react`/`ai-solid` `create-ui`
and drop the inline `import()` type in the Solid test (oxlint).
- Drop devDeps the deprecation commit orphaned in the `ai-*-ui` packages,
and alphabetize `ai-vue`'s (knip, sherif).
`pnpm test:ci` and `pnpm test:dts` both pass across all 86 projects.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* feat(ui): group createChatHook options and pass layout slots as components (#1282)
* feat(ui)!: hand layout and message components, not render thunks
`layout` now receives `Messages`, `Interrupts`, and `Input`; `message`
receives `Parts`. `renderMessages`, `renderInterrupts`, `renderInput`,
and `renderParts` are gone — this API ships first in this PR, so there
is nothing released to migrate.
React and Solid only. Vue and Svelte compose through slots and snippets
and already had empty `LayoutProps`.
`Messages` and `Interrupts` were already factory-closure declarations, so
passing them directly is strictly more stable than the `useCallback`
thunks they replace. `Parts` was the hard part: it closes over the
message, so the naive version builds a new component per render and
React remounts every part on each stream chunk. It now reads a
message-scoped context that `MessageView` provides, which makes it one
component for the factory's lifetime. `create-ui-stability.test.tsx`
pins that: the same `Parts` identity must survive a re-render with a new
message object.
`Input` is on the layout props only when the config registers an
`input`, so rendering one you never registered is a compile error rather
than a silent no-op. This is inferred from a `TInput` parameter on the
`input` property; a self-referential config constraint was tried first
and silently collapses to `false`.
Two inference caveats, both found by making the examples compile:
- Referencing the factory's own result inside its config
(`UI.useChatContext()`) is circular and blocks inference. The examples
and the e2e route now use `createChatHookContexts()`, already the
documented cycle-breaker.
- An inline `function` expression for `input` also blocks it. Arrows and
named references infer fine, so the examples hoist the component and
both UI docs call the trap out.
The default falls back to a union rather than `undefined` so that when
inference does degrade, `input` stays assignable and only `Input` goes
missing — a false negative instead of a rejected config.
Two doc snippets rendered an input they never registered; the new types
caught them.
`pnpm test:ci` and `pnpm test:dts` pass across all 86 projects.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(ui): warn instead of crashing on an unregistered Input
The conditional `Input` type hides the prop when no `input` is
registered, but that inference degrades on some config shapes, and the
runtime had no component to render in that case — React threw
"Element type is invalid" on an undefined element. Always supply a
component and warn once instead, matching the existing
"Missing tools.<name> component" warning. The floor is now consistent:
you find out at build time where inference works, and on the first dev
render where it doesn't.
The inference trigger turned out to be narrower than the previous commit
claimed. It is source order, not the `function` keyword: an inline
`function` expression for `input` infers fine as long as it is listed
before `layout`. Hoisting the component out of the config bought nothing
— the config literal is evaluated once at module scope, so an inline
component is already a stable reference — so the examples and the e2e
route go back to inline named components, ordered `input` first. Both UI
docs now describe the ordering rule rather than telling people to hoist.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* feat(ui)!: split createChatHook options into named component groups
`chatComponents` is gone. Registration is now flat on the factory call,
one group per kind:
createChatHook({
options,
context: { chatContext, partContext, interruptContext },
components: { input, layout, message },
toolsComponents: { ... },
interruptsComponents: { tools: { ... }, generic: { ... } },
partsComponents: { ... },
})
`createChatUI` takes the same shape as its second argument, so both
entry points register widgets identically. All four adapters (React,
Solid, Vue, Svelte) move together. Vue and Svelte keep their flat
internal runtime shape; the new config is mapped onto it at the factory
boundary, so nothing downstream of that changes.
`partsComponents` is plural, unlike the original sketch — the registries
are `parts`/`tools`/`interrupts` and the maps hold many entries;
`PartProps` and `ChatUIPartKey` stay singular because they describe one
part.
This also removes the `Input` inference fragility rather than
documenting around it. `layout` and `input` are now siblings inside
`components`, so TypeScript resolves that inner literal as a unit and
fixes `TInput` before contextually typing `layout`. Declaration order no
longer matters and an inline `function` expression works, both of which
broke inference when these keys sat at the config's top level. The
ordering caveat is out of both UI docs, and a type test pins the case
that used to fail so a future flattening cannot regress it silently.
Per instruction, no migration guidance was added anywhere; the existing
`docs/migration/create-ui.md` page covers the older package move only
and has been updated to the new shape rather than extended.
`pnpm test:ci` and `pnpm test:dts` pass across all 86 projects.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: drop migration guidance for the unreleased chat UI API
`createChatHook` and `createChatUI` have never been published, so
teaching them as something to migrate to was wrong. I checked before
cutting: `@tanstack/ai-react-ui@0.8.22` (and Solid 0.7.21, Vue 0.2.40)
export only the older `Chat` / `ChatMessages` / `ChatInput` compound
components, with no `createChatHook` anywhere.
So the page keeps the one migration that is real — swapping
`@tanstack/ai-*-ui` for the framework `/ui` subpath, which those
published packages do need — and loses the Before/After, Steps, and
Gotchas sections that walked through adopting the new factory. The new
API is documented in the UI guides as a new API.
The `Chat` component's `@deprecated` notices pointed at that page for
`createChatHook` guidance, so they now point at the matching UI guide.
The `docs/api/*` pages no longer advertise the migration page as reading
for the typed chat UI. The `*-ui` shim packages still link there, which
is still exactly what that page covers.
Also brings this branch in line with repo rules I had been working
without, having only picked up the worktree's CLAUDE.md late:
- Removed the em dashes the docs skill forbids from text added here.
- Bumped `updatedAt` in `docs/config.json` for the five pages with real
content changes. The four `docs/api/*` pages only lost a stale link,
which the rule classes as a factual fix that must not bump.
- Rewrote the `create-chat-hook` changeset to describe the shipping
option groups instead of the old `chatComponents` shape, and aligned
`typed-headless-chat-ui` with the new names. Since none of this has
released, these describe the API rather than a change to it.
`pnpm test:ci` and `pnpm test:dts` pass across all 86 projects.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* test(e2e): pin the Parts subtree against remounting mid-stream
`CLAUDE.md` requires E2E coverage for a behavior change and this stack
had none. The behavior worth guarding is the reason `Parts` reads a
message-scoped context instead of closing over the message: a `Parts`
rebuilt per render makes React remount every part on each stream chunk,
throwing away local state in tool and part widgets.
The purchase tool widget on `/headless-ui` now stamps a per-mount
sequence into `data-mount-seq`, and the spec asserts it stays at 1 across
the tool-call chunks and again across the resume stream after approval.
Verified the test actually catches the regression rather than just
passing: reverting `Parts` to a per-render closure and rebuilding takes
the widget to 7 mounts, and the assertion fails on the first check.
Full suite: 638 passed, 10 failed. Both failing specs
(`multi-turn-structured` across providers, and the flaky
`durable-takeover`) fail identically on the PR base `
|
History
|
|
|---|---|---|
| .. | ||
| public | ||
| src | ||
| .cta.json | ||
| .env.example | ||
| .gitignore | ||
| api-verification.ts | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
| vite.config.ts | ||
Welcome to your new TanStack app!
Getting Started
To run this application:
pnpm install
pnpm start
Building For Production
To build this application for production:
pnpm build
Testing
This project uses Vitest for testing. You can run the tests with:
pnpm test
Styling
This project uses Tailwind CSS for styling.
TanStack Chat Application
An example chat application built with TanStack Start, TanStack Store, and TanStack AI (our open-source AI SDK).
.env Updates
OPENAI_API_KEY=your_openai_api_key
✨ Features
AI Capabilities
- 🤖 Powered by TanStack AI with OpenAI GPT-4o
- 📝 Rich markdown formatting with syntax highlighting
- 🎯 Customizable system prompts for tailored AI behavior
- 🔄 Real-time streaming responses with Server-Sent Events
- 🔌 Connection adapters - flexible streaming architecture
- 🛠️ Automatic tool execution loop - tools are executed automatically by the SDK
- 🎸 Tool/function calling with guitar recommendations
User Experience
- 🎨 Modern UI with Tailwind CSS and Lucide icons
- 🔍 Conversation management and history
- 🔐 Secure API key management
- 📋 Markdown rendering with code highlighting
Technical Features
- 📦 Centralized state management with TanStack Store
- 🔌 Extensible architecture for multiple AI providers
- 🛠️ TypeScript for type safety
Architecture
Tech Stack
- Frontend Framework: TanStack Start
- Routing: TanStack Router
- State Management: TanStack Store
- Styling: Tailwind CSS
- AI Integration: TanStack AI with OpenAI GPT-4o
- Chat Client:
@tanstack/ai-solidwith connection adapters - Streaming: Server-Sent Events via
fetchServerSentEvents - Tool Execution: Automatic loop with
ToolCallManager
Routing
This project uses TanStack Router. The initial setup is a file based router. Which means that the routes are managed as files in src/routes.
Adding A Route
To add a new route to your application just add another a new file in the ./src/routes directory.
TanStack will automatically generate the content of the route file for you.
Now that you have two routes you can use a Link component to navigate between them.
Adding Links
To use SPA (Single Page Application) navigation you will need to import the Link component from @tanstack/solid-router.
import { Link } from '@tanstack/solid-router'
Then anywhere in your JSX you can use it like so:
<Link to="/about">About</Link>
This will create a link that will navigate to the /about route.
More information on the Link component can be found in the Link documentation.
Using A Layout
In the File Based Routing setup the layout is located in src/routes/__root.tsx. Anything you add to the root route will appear in all the routes. The route content will appear in the JSX where you use the <Outlet /> component.
Here is an example layout that includes a header:
import { Outlet, createRootRoute } from '@tanstack/solid-router'
import { TanStackRouterDevtools } from '@tanstack/solid-router-devtools'
import { Link } from '@tanstack/solid-router'
export const Route = createRootRoute({
component: () => (
<>
<header>
<nav>
<Link to="/">Home</Link>
<Link to="/about">About</Link>
</nav>
</header>
<Outlet />
<TanStackRouterDevtools />
</>
),
})
The <TanStackRouterDevtools /> component is not required so you can remove it if you don't want it in your layout.
More information on layouts can be found in the Layouts documentation.
Data Fetching
There are multiple ways to fetch data in your application. You can use TanStack Query to fetch data from a server. But you can also use the loader functionality built into TanStack Router to load the data for a route before it's rendered.
For example:
const peopleRoute = createRoute({
getParentRoute: () => rootRoute,
path: '/people',
loader: async () => {
const response = await fetch('https://swapi.dev/api/people')
return response.json() as Promise<{
results: {
name: string
}[]
}>
},
component: () => {
const data = peopleRoute.useLoaderData()
return (
<ul>
{data.results.map((person) => (
<li key={person.name}>{person.name}</li>
))}
</ul>
)
},
})
Loaders simplify your data fetching logic dramatically. Check out more information in the Loader documentation.
Solid-Query
Solid-Query is an excellent addition or alternative to route loading and integrating it into you application is a breeze.
First add your dependencies:
pnpm add @tanstack/solid-query @tanstack/solid-query-devtools
Next we'll need to create a query client and provider. We recommend putting those in main.tsx.
import { QueryClient, QueryClientProvider } from '@tanstack/solid-query'
// ...
const queryClient = new QueryClient()
// ...
You can also add TanStack Query Devtools to the root route (optional).
import { SolidQueryDevtools } from '@tanstack/solid-query-devtools'
const rootRoute = createRootRoute({
component: () => (
<>
<Outlet />
<SolidQueryDevtools buttonPosition="top-right" />
<TanStackRouterDevtools />
</>
),
})
Now you can use useQuery to fetch your data.
import { useQuery } from '@tanstack/solid-query'
import './App.css'
function App() {
const { data } = useQuery({
queryKey: ['people'],
queryFn: () =>
fetch('https://swapi.dev/api/people')
.then((res) => res.json())
.then((data) => data.results as { name: string }[]),
initialData: [],
})
return (
<div>
<ul>
{data.map((person) => (
<li key={person.name}>{person.name}</li>
))}
</ul>
</div>
)
}
export default App
You can find out everything you need to know on how to use Solid-Query in the Solid-Query documentation.
State Management
Another common requirement for Solid applications is state management. There are many options for state management in Solid. TanStack Store provides a great starting point for your project.
First you need to add TanStack Store as a dependency:
pnpm add @tanstack/store
Now let's create a simple counter in the src/App.tsx file as a demonstration.
import { useStore } from '@tanstack/solid-store'
import { Store } from '@tanstack/store'
import './App.css'
const countStore = new Store(0)
function App() {
const count = useStore(countStore)
return (
<div>
<button onClick={() => countStore.setState((n) => n + 1)}>
Increment - {count}
</button>
</div>
)
}
export default App
One of the many nice features of TanStack Store is the ability to derive state from other state. That derived state will update when the base state updates.
Let's check this out by doubling the count using derived state.
import { useStore } from '@tanstack/solid-store'
import { Store, Derived } from '@tanstack/store'
import './App.css'
const countStore = new Store(0)
const doubledStore = new Derived({
fn: () => countStore.state * 2,
deps: [countStore],
})
doubledStore.mount()
function App() {
const count = useStore(countStore)
const doubledCount = useStore(doubledStore)
return (
<div>
<button onClick={() => countStore.setState((n) => n + 1)}>
Increment - {count}
</button>
<div>Doubled - {doubledCount}</div>
</div>
)
}
export default App
We use the Derived class to create a new store that is derived from another store. The Derived class has a mount method that will start the derived store updating.
Once we've created the derived store we can use it in the App component just like we would any other store using the useStore hook.
You can find out everything you need to know on how to use TanStack Store in the TanStack Store documentation.
Demo files
Files prefixed with demo can be safely deleted. They are there to provide a starting point for you to play around with the features you've installed.
Learn More
You can learn more about all of the offerings from TanStack in the TanStack documentation.