AI Chat Channels and Streaming

Purpose and Scope

The helpers package gives frontend teams a deterministic way to build, preview, document, and test streaming chat interfaces without depending on a live model or backend route. The reader problem is concrete: a chat UI often needs to render partial assistant text, reasoning, tool states, source cards, loading indicators, and disabled controls before the production integration is ready. The AI SDK guide says the helper writes a conversation in code and streams it through the real chat lifecycle with no model, API route, network request, or API key. Sources: apps/v4/content/docs/helpers/ai-sdk.mdx, apps/v4/content/docs/changelog/2026-07-helpers.mdx

This page covers the public helper primitives for two channel-style integrations: the AI SDK adapter and the TanStack AI adapter. Both adapters start from the same authoring idea, a scripted conversation that alternates user and assistant turns, but each targets the receiving framework’s native chat contract. The helpers navigation metadata places these pages together under the helper documentation section, and the launch changelog describes them as the first focused utilities in the package. Treat them as development-time conversation drivers, not as replacements for production model orchestration. Sources: apps/v4/content/docs/helpers/meta.json, apps/v4/content/docs/helpers/tanstack-ai.mdx, apps/v4/content/docs/changelog/2026-07-helpers.mdx

Relevant Source Files

• apps/v4/content/docs/helpers/ai-sdk.mdx - First-party guide for the AI SDK helper, including installation, conversation authoring, initial messages, local transport, next-message advancement, supported message parts, and useChat integration.
• packages/helpers/src/ai-sdk/index.ts - Public AI SDK helper barrel that exports createChat and the AiSdkChat and CreateChatOptions types from the chat module.
• apps/v4/content/docs/changelog/2026-07-helpers.mdx - Release announcement for @shadcn/helpers, including the package rationale, writer example, streaming lifecycle claims, and adapter list.
• apps/v4/content/docs/helpers/meta.json - Helpers documentation navigation metadata showing ai-sdk and tanstack-ai as the public helper pages.
• apps/v4/content/docs/helpers/tanstack-ai.mdx - First-party guide for the TanStack AI helper, including native UIMessage values, local connection behavior, AG-UI event replay, append flow, and usage example.
• apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx - Historical distribution context for shadcn code, remote installation, registries, monorepo support, and the project direction toward code accessible to developers and LLMs.

Core Primitives

The central primitive is a chat builder created with the helper entry point. In the AI SDK package entry, the public module re-exports the builder and the primary types, which makes the supported import surface intentionally small. The docs show the builder as a chain of user and assistant turns. That chain is more than fixture text: it can produce a starting transcript, determine the next scripted user message from current messages, and provide a local adapter that drives the framework chat hook. Sources: packages/helpers/src/ai-sdk/index.ts, apps/v4/content/docs/helpers/ai-sdk.mdx

The second primitive is the local stream adapter. In the AI SDK guide, the adapter is passed as transport to the framework hook. In the TanStack AI guide, the same helper method supplies a connection because that is the TanStack hook option name. This naming difference is important when porting demos between frameworks. The AI SDK example sends the next predefined user message through the hook’s send function, while the TanStack example appends it. In both cases, the assistant reply is streamed by the local adapter rather than directly inserted as finished content. Sources: apps/v4/content/docs/helpers/ai-sdk.mdx, apps/v4/content/docs/helpers/tanstack-ai.mdx

The third primitive is the assistant writer callback used for richer scripted turns. The helper announcement demonstrates a response that starts a step, emits reasoning, creates a tool call with input, waits, produces tool output, adds a source URL, and finally streams text. That sequence explains why the package is useful for realistic interface work: a component can exercise intermediate states that plain static messages cannot cover. Tool cards can move from pending to completed, reasoning panels can fill in over time, and final answer text can arrive after supporting context. Sources: apps/v4/content/docs/changelog/2026-07-helpers.mdx

Execution Flow

A typical AI SDK workflow starts by installing the helpers package and importing the AI SDK helper path alongside the existing chat hook. Define the scripted conversation outside the component so that the same scenario is reused across renders. Then compute the starting transcript with a zero count when the UI should open empty, create the local transport, and pass both into the hook. During rendering, ask the chat builder for the next user message based on the current transcript, and disable the send control when there is no next message or when the hook is already submitting or streaming. Sources: apps/v4/content/docs/helpers/ai-sdk.mdx

import { useChat } from "@ai-sdk/react"
import { createChat } from "@shadcn/helpers/ai-sdk"
 
const chat = createChat()
  .user("What changed in this release?")
  .assistant("The release adds keyboard shortcuts and faster search.")
 
const initialMessages = chat.get(0)
const transport = chat.transport()
 
export function Demo() {
  const { messages, sendMessage, status } = useChat({
    messages: initialMessages,
    transport,
  })
 
  const nextMessage = chat.next(messages)
  const isBusy = status === "submitted" || status === "streaming"
 
  return (
    <button disabled={!nextMessage || isBusy} onClick={() => nextMessage && sendMessage(nextMessage)}>
      Send
    </button>
  )
}

TanStack AI follows the same conceptual flow, but the names at the integration boundary change. The guide imports the TanStack helper path and the TanStack React hook, passes initial messages as the hook’s starting state, and supplies the local adapter as a connection. When a user action advances the script, the example calls append with the next predefined user message. The local connection then replays the assistant response as real AG-UI events, so the receiving components observe text and reasoning streaming word by word and tool calls moving from input to result. Sources: apps/v4/content/docs/helpers/tanstack-ai.mdx

API Components and Adapter Differences

The compact public contract is deliberately easy to remember. Author a conversation with the builder, request initial messages, create the local adapter, ask for the next scripted user turn, and hand that message back to the framework hook. For AI SDK consumers, the guide states that the hook receives typed UIMessage values and that every part type supported by the AI SDK is supported by the helper, including reasoning, tools, data, files, sources, and custom parts. That makes it suitable for components whose rendering branches depend on message part types rather than only on roles. Sources: apps/v4/content/docs/helpers/ai-sdk.mdx, packages/helpers/src/ai-sdk/index.ts

TanStack AI consumers should keep the same authoring model but use TanStack’s native message and event terminology at the edge. The TanStack guide emphasizes native TanStack UIMessage arrays and AG-UI events from the local connection. From a component author’s perspective, the practical differences are the hook package, the hook option names, and the method used to send the next user message. The conversation definition can remain familiar, but examples should not mix AI SDK names such as transport and sendMessage with TanStack names such as connection and append. Sources: apps/v4/content/docs/helpers/tanstack-ai.mdx

Compact Reference

Design Context, Edge Cases, and Testing Signals

These helpers fit the broader shadcn/ui distribution model of shipping code that developers can inspect, adapt, and automate against. The earlier CLI rewrite expanded installation across frameworks, remote components, registries, hooks, utilities, and monorepo support, and described that direction as distributing code that users and LLMs can access. The helpers package applies the same open-code idea to AI interface development. Instead of hiding behavior behind a service, it lets teams describe the conversation scenario in local code and run the visible UI through meaningful streaming states. Sources: apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx, apps/v4/content/docs/changelog/2026-07-helpers.mdx

The most common edge case is double advancement. The docs’ fuller examples compute a busy flag from submitted and streaming statuses and disable the button while a response is in flight. That matters because the helper maps a predefined user turn to its paired assistant stream; sending another turn before the previous stream settles can make a demo harder to reason about. Another edge case is starting state. A zero-count transcript opens with no visible messages, but teams can choose a different starting point when a preview should begin after earlier context has already been exchanged. Sources: apps/v4/content/docs/helpers/ai-sdk.mdx, apps/v4/content/docs/helpers/tanstack-ai.mdx

Use the helpers in tests and previews when the assertion depends on timing, intermediate states, or repeatability. The docs explicitly call out CI usage with no network calls, token spend, or flaky model output. For visual work, script the exact states your product renders: a short text-only answer, a long streamed answer, a reasoning segment, a tool invocation, a source citation, and a file or custom part if your UI supports them. That gives designers and developers a stable scenario for comparing layout, animation, accessibility, and empty-state behavior across revisions. Sources: apps/v4/content/docs/helpers/ai-sdk.mdx, apps/v4/content/docs/helpers/tanstack-ai.mdx, apps/v4/content/docs/changelog/2026-07-helpers.mdx

Next Steps

Choose the adapter that matches the chat framework already used by the application. Start with one short conversation and wire it through the hook exactly as the relevant guide shows. After the basic send flow works, add writer-driven details that exercise the UI states you actually ship: reasoning panels, tool cards, source rows, loading placeholders, and streamed final text. If the work is part of a design system or documentation site, keep the conversation near the component preview so future contributors can understand which states the example is intended to cover.

For adjacent reading, pair this page with React hooks and instrumentation when the transcript needs robust scrolling behavior, because deterministic streams are most valuable when viewport behavior is also tested under pressure. Read the MCP pages when the problem shifts from local scripted conversations to tool-assisted registry discovery or installation. Read the registry pages when you want to distribute reusable chat components, previews, or helper-driven examples as installable code rather than only documenting them inside one application.