# Update
> Upgrades an existing assistant-ui application and applies the migrations needed to reach the current AI SDK v7 and assistant-ui 0.15.x lines. Use when updating, bumping, or migrating @assistant-ui/react, @assistant-ui/ai-sdk, the older @assistant-ui/react-ai-sdk alias, ai, or @ai-sdk/react, or when an upgrade exposes removed hooks, scope accessor calls, provider configuration, registry paths, event names, legacy interactables, or tool registrations. Start here for an existing project, post-update type failures, package compatibility, CLI codemods, and version-specific migration order. For a first install or a new project use setup; for authoring a runtime without an upgrade use runtime.
- Skill: `assistant-ui-skills/update` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add assistant-ui-skills/update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/assistant-ui-skills/update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: assistant-ui (https://skillmd.com/u/assistant-ui-skills)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/assistant-ui-skills/update
---
# assistant-ui Update
**Always consult [assistant-ui.com/llms.txt](https://www.assistant-ui.com/llms.txt) for the latest API.**
Upgrade in two passes. First make the AI SDK and its assistant-ui adapter compatible, then update assistant-ui and apply its API migration. Read the relevant references before editing because a direct jump can cross several deprecation windows.
## References
- [./references/ai-sdk.md](./references/ai-sdk.md) -- AI SDK v4 and v5 to v6 migration, v6 to v7 changes, and adapter pins
- [./references/assistant-ui.md](./references/assistant-ui.md) -- assistant-ui 0.8 through 0.15, toolkits, LangGraph, and deprecation policy
- [./references/breaking-changes.md](./references/breaking-changes.md) -- quick version and symptom lookup
## Detect the installed lines
Run these commands from the application root. npm ls reports the installed dependency graph and npm view reports the published latest version.
```bash
npm ls @assistant-ui/react @assistant-ui/ai-sdk @assistant-ui/react-ai-sdk @assistant-ui/core @assistant-ui/store assistant-stream ai @ai-sdk/react
npm view @assistant-ui/react version
npm view @assistant-ui/ai-sdk version
npm view @assistant-ui/react-ai-sdk version
npm view @assistant-ui/core version
npm view @assistant-ui/store version
npm view assistant-stream version
npm view ai version
npm view @ai-sdk/react version
```
Current published lines as of September 2026:
| Package | Current line |
| --- | --- |
| assistant-ui | 0.0.x |
| @assistant-ui/react | 0.15.x |
| @assistant-ui/ai-sdk | 0.0.x |
| @assistant-ui/react-ai-sdk | 1.4.x |
| @assistant-ui/core | 0.3.x |
| @assistant-ui/store | 0.3.x |
| assistant-stream | 0.3.x |
| assistant-cloud | 0.1.x |
| ai | 7.x |
@assistant-ui/react-ai-sdk re-exports the same API for older installs. New code imports from @assistant-ui/ai-sdk.
## Choose the migration set
Compare the installed @assistant-ui/react version against every threshold below. Apply every applicable guide in ascending version order.
| Installed before | Check for |
| --- | --- |
| 0.8.x | The historical UI package split. The current upgrade bundle intentionally excludes v0-8/ui-package-split because its destination is incompatible with current runtimes. Move to the Elements registry manually. |
| 0.9.x | The v0-9/edge-package-split codemod. |
| 0.10.x | The bundled migration has no dedicated 0.10 codemod. Run the later codemods and resolve remaining package or build errors from the project’s current toolchain. |
| 0.11.x | ContentPart names and MessagePrimitive.Content become MessagePart and MessagePrimitive.Parts. |
| 0.12.x | Unified state API, hook aliases, and camelCase event names. |
| 0.13.x | Review the 0.14 guide before proceeding because it removes the v0.11 and v0.12 deprecations. |
| 0.14.x | Removed aliases and runtime APIs, plus primitive children render functions. |
| 0.15.x | Scope properties, removed legacy hooks, toolUIs, standalone-tool-call, AuiConfig, and threads.selectionChanged. |
## Migration order
1. Migrate the AI SDK first. Read [ai-sdk.md](./references/ai-sdk.md) when the project is on v4, v5, or v6. Target ai@^7 and @ai-sdk/react@^4 with @assistant-ui/ai-sdk.
2. Update assistant-ui next. Use the threshold table and [assistant-ui.md](./references/assistant-ui.md), starting with the oldest applicable version.
3. Verify only after the package and source migrations are both complete. Typecheck, build, and exercise chat, tool, approval, and thread-selection paths that the application uses.
## Run the CLI
```bash
# Update every installed @assistant-ui/* package.
npx assistant-ui@latest update
# Preview package changes without installing them.
npx assistant-ui@latest update --dry
# Preview the complete bundled migration and print each transformed file.
npx assistant-ui@latest upgrade -d -p
# Apply one codemod to a source directory.
npx assistant-ui@latest codemod v0-11/content-part-to-message-part ./src
# Report environment and dependency details.
npx assistant-ui@latest doctor
npx assistant-ui@latest info
```
The bundled upgrade command runs these codemods in this exact order:
1. v0-9/edge-package-split
2. v0-11/content-part-to-message-part
3. v0-12/assistant-api-to-aui
4. v0-12/event-names-to-camelcase
5. v0-12/primitive-if-to-aui-if
6. v0-15/aui-accessor-calls-to-properties
Use the dry and print form first. After reviewing the diff, run upgrade without -d and -p. Do not add the historical v0-8/ui-package-split codemod to a current upgrade.
## 0.15.x follow-ups
These changes shipped after 0.15.0 without another major. Sweep for them even if the project already declares 0.15.x.
### Move the AI SDK import
```tsx
// Before
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
```
```tsx
// After
import { useChatRuntime } from "@assistant-ui/ai-sdk";
```
### Replace client construction with configuration
useAui takes no configuration. Build a configuration with AuiConfig and give it to the provider. A nested AuiProvider must declare whether it extends the parent client or is isolated.
```tsx
// Before
const aui = useAui({ tools: Tools({ toolkit }) });
return {children};
```
```tsx
// After
const aui = useAui();
const config = AuiConfig({ tools: Tools({ toolkit }) });
return {children};
```
At a runtime boundary, replace AssistantRuntimeProvider aui with config. For an isolated root, use AuiProvider extends={null} config={config}.
```tsx
// Before
return {children};
```
```tsx
// After
const config = AuiConfig({ tools: Tools({ toolkit }) });
return {children};
```
### Move copied registry components
Runtime-connected registry components live at components/assistant-ui/elements/.aui.tsx and import as @/components/assistant-ui/elements/.aui. Renderers and standalone Elements use components/assistant-ui/elements/.tsx and omit .aui from their import. Replace retired @/components/assistant-ui/ imports during the same sweep.
### Consolidate thread selection events
```tsx
// Before
useAuiEvent("threadListItem.switchedTo", ({ threadId }) => select(threadId));
useAuiEvent("threadListItem.switchedAway", ({ threadId }) => clear(threadId));
```
```tsx
// After
useAuiEvent("threads.selectionChanged", ({ threadId, previousThreadId }) => {
select(threadId);
if (previousThreadId) clear(previousThreadId);
});
```
The new event is shared by the threads scope. A listener that previously lived inside a thread-list item can filter by its item id.
### Replace legacy interactables and tool registrations
useAssistantInteractable, Interactables(), and useInteractableState are deprecated since 2026-06-14 and scheduled for removal on or after 2026-09-14. Migrate to unstable_useInteractable, unstable_Interactables(), and unstable_interactableTool.
makeAssistantTool, useAssistantTool, makeAssistantToolUI, and useAssistantToolUI are deprecated. Put the model contract, executor, and renderer in a defineToolkit entry and register it with AuiConfig({ tools: Tools({ toolkit }) }). Read the toolkits section in [assistant-ui.md](./references/assistant-ui.md) before converting stateful or UI-only tools.
## Verify
```bash
npx tsc --noEmit
npm run build
npm test
```
Also open a real chat route and verify an ordinary message, a tool call, an approval gate if present, a thread switch, and the project’s persisted-history path. Run npx assistant-ui@latest doctor and npx assistant-ui@latest info when a dependency or environment mismatch remains.
## Common Gotchas
**The upgrade command changed imports but the app still uses the old adapter**
- The package update only covers @assistant-ui packages. Update ai and @ai-sdk/react separately, then follow the AI SDK reference.
- @assistant-ui/react-ai-sdk is an alias for older installs. Current source imports from @assistant-ui/ai-sdk.
**AuiProvider or AssistantRuntimeProvider no longer accepts the old props**
- useAui() is context access only. Build AuiConfig({...}) and pass it as config.
- A nested AuiProvider needs extends={aui}; an isolated one needs extends={null}.
**A scope lookup no longer behaves like a null check**
- aui.thread is always truthy. Check aui.thread.source != null before accessing an optional scope.
- Scope accessors are properties. Call scope methods, not the scope itself.
**The typecheck still finds removed hooks or tool maps**
- Apply the full removed-hook mapping in [assistant-ui.md](./references/assistant-ui.md).
- Replace s.tools.tools with s.tools.toolUIs and the mcp-app group key with standalone-tool-call.
## Related Skills
- [setup](../setup/SKILL.md) -- install assistant-ui into a project that has not used it before
- [runtime](../runtime/SKILL.md) -- build or customize an active runtime after the migration
- [tools](../tools/SKILL.md) -- author toolkits, frontend tools, approvals, and tool UI
- [elements](../elements/SKILL.md) -- install and customize the copied Elements registry components