agentleFS
skilld-devskilld-dev/vue-ecosystem-skills/skills/tanstack-ai-vue-skilld/SKILL.md

tanstack-ai-vue-skilld

Skill184 starsChanged 37 days agoMITView on GitHub

Use when writing or debugging Vue code that imports @tanstack/ai-vue. Covers useChat, createChatHook, the generation composables (image, audio, speech, video, transcription, summarize), useAudioRecorder, useByok, useWebMCPTools, and the @tanstack/ai-vue/ui and /byok subpaths. Provides current API shapes, reactive-state rules, and version limits for @tanstack/ai-vue 0.24.x.

  • Installs packages

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every composable must run inside a component setup or effect scope.

    line 19
  2. Very specific:

    All reactive state is DeepReadonly<ShallowRef<T>>.

    line 20
  3. Very specific:

    Prefer forwardedProps over body.

    line 24
  4. Very specific:

    All follow one pattern: pass connection or fetcher, call generate(input), read reactive state.

    line 108

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

@tanstack/ai-vue

Vue 3 composables for TanStack AI streaming chat, structured outputs, and media generation. Wraps the headless @tanstack/ai-client classes (ChatClient, GenerationClient, VideoGenerationClient) in reactive state.

  • Version documented: 0.24.3 (source: package.json:3)
  • Peer deps: vue >=3.5.0, @tanstack/ai ^0.58.0; runtime deps: @tanstack/ai-client ^0.33.2, @tanstack/markdown ^0.0.13 (source: package.json:55-62)
  • Entry points: . (main), ./ui (headless chat UI factory), ./byok (bring-your-own-key) (source: package.json:23-36)
  • Official docs: https://tanstack.com/ai/latest/docs/api/ai-vue and https://tanstack.com/ai/latest/docs/getting-started/quick-start-vue
  • Install: pnpm add @tanstack/ai @tanstack/ai-vue @tanstack/ai-openai (plus a provider adapter; server-side chat comes from @tanstack/ai)

Core rules

  1. Every composable must run inside a component setup or effect scope. Cleanup is automatic via onScopeDispose; the scope owns the connection (source: src/use-chat.ts:259-269).
  2. All reactive state is DeepReadonly<ShallowRef<T>>. Read with .value in script AND template. Never reassign; use the returned methods (setMessages, clear, reset) (source: src/use-chat.ts:425-457).
  3. Pass a connection adapter (for example fetchServerSentEvents('/api/chat'), re-exported from this package) or a fetcher. Generation hooks throw useGeneration requires either a connection or fetcher option without one (source: src/use-generation.ts:272-274).
  4. useChat builds one ChatClient per call. Changing connection (or other transport identity) requires a remount or a changed key prop; body, forwardedProps, context, and queue are watched and synced live (source: src/types.ts:77-79, src/use-chat.ts:212-230).
  5. Callback options (onChunk, onFinish, onError, ...) are read through the options object at call time, so reactive or mutated options propagate without recreating the client (source: src/use-chat.ts:85-91).
  6. Prefer forwardedProps over body; body is deprecated but still merged into the same wire payload (source: src/use-chat.ts:207-209).

Quick start: streaming chat

Server (Express or any backend returning TanStack AI SSE):

import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'

app.post('/api/chat', async (req, res) => {
  const stream = chat({ adapter: openaiText('gpt-4o'), messages: req.body.messages })
  const response = toServerSentEventsResponse(stream)
  // pipe response.body to res
})

Client component:

<script setup lang="ts">
import { ref } from 'vue'
import { useChat, fetchServerSentEvents } from '@tanstack/ai-vue'

const input = ref('')
const { messages, sendMessage, isLoading } = useChat({
  connection: fetchServerSentEvents('/api/chat'),
})

function handleSubmit() {
  if (input.value.trim() && !isLoading.value) {
    sendMessage(input.value)
    input.value = ''
  }
}
</script>

<template>
  <div v-for="message in messages.value" :key="message.id">
    <div v-for="(part, idx) in message.parts" :key="idx">
      <p v-if="part.type === 'text'">{{ part.content }}</p>
    </div>
  </div>
  <form @submit.prevent="handleSubmit">
    <input v-model="input" :disabled="isLoading.value" />
    <button type="submit">Send</button>
  </form>
</template>

Source: official quick start, https://tanstack.com/ai/latest/docs/getting-started/quick-start-vue

Typed tools

Define tools once with toolDefinition() from @tanstack/ai, implement .client(fn) in components, and wrap them in clientTools() (re-exported here from @tanstack/ai-client) so part.name, part.input, and part.output narrow without as const. Client tools execute automatically; there is no onToolCall option. Derive message types with createChatClientOptions + InferChatMessages (both re-exported). Source: https://tanstack.com/ai/latest/docs/api/ai-vue

<script setup lang="ts">
import { useChat, fetchServerSentEvents, clientTools } from '@tanstack/ai-vue'
import { updateUIDef } from './tool-definitions'

const updateUI = updateUIDef.client((input) => {
  notification.value = input.message
  return { success: true }
})

const { messages, sendMessage } = useChat({
  connection: fetchServerSentEvents('/api/chat'),
  tools: clientTools(updateUI),
})
</script>

Shared chat hook

createChatHook(options) (root entry) binds options at module scope and returns a useChat composable. Override only threadId, live, forwardedProps, body, and initialMessages per instance; tools, interrupts, and outputSchema stay on the factory options. Rename at the call site if it clashes with the imported useChat (source: src/create-chat-hook.ts:28-45).

const { useChat: useAppChat } = createChatHook(chatOptions)
const chat = useAppChat({ threadId: 'support-1' })

Generation composables

All follow one pattern: pass connection or fetcher, call generate(input), read reactive state.

ComposableInput typeResult typeExtras
useGenerationcustom TInputcustom TResultbase composable for custom types
useGenerateImageImageGenerateInputImageGenerationResult
useGenerateAudioAudioGenerateInputAudioGenerationResult
useGenerateSpeechSpeechGenerateInputTTSResult
useTranscriptionTranscriptionGenerateInputTranscriptionResult
useSummarizeSummarizeGenerateInputSummarizationResult
useGenerateVideoVideoGenerateInputVideoGenerateResultjobId, videoStatus, onJobCreated, onStatusUpdate

Common return: generate, result, isLoading, error, status, stop, reset, runId. Details, transforms, and persistence: references/generation-composables.md

stop() only aborts the local stream. It does not stop work already running on the provider; use runId against your own endpoint to cancel or poll (source: src/use-generation.ts:124-131).

Chat UI (@tanstack/ai-vue/ui)

Build chat interfaces with createChatHook from the /ui subpath (not the deprecated prebuilt components Chat, ChatInput, ChatMessage, ChatMessages, ToolApproval, deprecated since 0.3.0, removal planned for 1.0.0). The subpath also exports renderless UIChat, UIProvider, UIMessages, UIMessage, UIPart, UIInterrupts, UIQueue, and createChatUI / createChatHookContexts. This subpath ships as raw .ts/.vue source, so it is type-checked against your tsconfig (source: package.json:28-31, src/ui.ts:2-33, src/chat-ui/types.ts:5).

Guide: references/chat-ui.md

BYOK and WebMCP

  • useByok(client) turns a ByokClient into a reactive ByokSnapshot; build the client with defineByok, ByokClient, passkeyStorage, and friends from the /byok subpath. Keys travel in x-byok-* headers, never the request body (source: src/use-byok.ts:5-14, src/use-generation.ts:35-38).
  • useWebMCPTools([searchProducts]) registers executable client tools with WebMCP for the current scope; disposal unregisters them (source: src/use-web-mcp-tools.ts:27-55).

Guide: references/byok-and-webmcp.md

Troubleshooting

  • State not updating in templates: these are ShallowRefs. Use isLoading.value inside templates too.
  • useChat ignored an option change: transport identity (connection, threadId persistence shape) is fixed per instance. Remount or change the component key (source: src/types.ts:77-79).
  • Approval response rejected: addToolApprovalResponse takes the approval id (part.approval.id), not the tool call id (source: src/types.ts:193-199).
  • Hydrated nothing on reload: persistence requires a stable threadId; without one the client mints an id after mount and the chat stays ephemeral (source: src/use-chat.ts:101-103).

References

  • useChat API: options, full return shape, structured outputs, interrupts, queue, live mode, resume.
  • Generation composables: useGeneration and the six specialized hooks, onResult transforms, persistence, useAudioRecorder.
  • Chat UI: the /ui subpath, factory config, renderless components, migration off deprecated components.
  • BYOK and WebMCP: the /byok subpath, useByok, useWebMCPTools.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.