docs: fix outdated adapter/tool APIs and add typed-options guide#635
Merged
Conversation
Sweep across docs to bring examples back in line with the current
public surface, plus a new guide for the createXxxOptions family.
Broken-import fixes (would have failed for users on copy-paste):
- openai/gemini: openaiTTS/geminiTTS -> openaiSpeech/geminiSpeech
- openai/anthropic/gemini: OpenAIChatConfig/AnthropicChatConfig/
GeminiChatConfig -> *TextConfig
- openai/anthropic/gemini: corrected the createXxxChat curry pattern
to the real (model, apiKey, config?) signature
- groq: removed fictional groqSpeech TTS section
- grok: corrected false "no TTS / no transcription" limitations and
documented grokSpeech, grokTranscription, grokRealtime; fixed
toStreamResponse -> toServerSentEventsResponse
- fal: removed fictional createFalImage / createFalVideo aliases
- elevenlabs: added Speech / Audio / Transcription sections
- ollama: corrected ollamaText / createOllamaChat factory signatures
- media/text-to-speech: global TTS -> Speech rename, fixed missing
model args and explicit-API-key examples
- advanced/multimodal-content: removed fabricated assertMessages
section, replaced with a Standard-Schema validation example
- advanced/middleware: toolCacheMiddleware imports point at the
@tanstack/ai/middlewares subpath where the symbol actually lives
- getting-started overview / quick-start: added missing `z` imports
- getting-started quick-start-vue + api/ai-vue: corrected Vue
template antipattern (refs auto-unwrap in templates; .value is
only needed inside <script setup>)
- tools/tool-approval: corrected ToolCallState lifecycle to the
real enum (awaiting-input, input-streaming, input-complete,
approval-requested, approval-responded, complete); use part.input
instead of stringifying the JSON-string part.arguments
- tools/client-tools: replaced invented `completed` state with the
real `complete` state and fixed a broken state-check snippet
- tools/tool-architecture: part.arguments.to (string treated as
object) -> part.input.to
- tools/tools, server-tools: "JSON Schema infers `any`" -> the real
behavior is `unknown` (Standard Schema validators give full
inference)
- code-mode: removed legacy chat({ model: "..." }) field
- generateSpeech JSDoc + auto-generated reference: openaiTTS ->
openaiSpeech so docs stay correct after the next regenerate
New content:
- docs/advanced/typed-options.md — covers the full createXxxOptions
family (chat, summarize, image, audio, video, speech,
transcription), what they do (capture an adapter's full type so
options stay narrowed when spread), what they don't (no runtime
behavior), with journey-style examples. Added to config.json nav.
Verified with `pnpm test:docs` (298 markdown files, no broken links)
and `pnpm --filter @tanstack/ai test:types`.
Contributor
|
Caution Review failedPull request was closed or merged during review 📝 WalkthroughWalkthroughThis PR updates TanStack AI documentation to standardize adapter factory APIs across providers, rename OpenAI TTS to Speech, expand ElevenLabs and Grok capabilities, update tool approval states, clarify Vue ref handling, and introduce a new typed options guide. ChangesAdapter Factory API Standardization
Adapter Capability Updates
OpenAI Speech API Renaming
Tool Approval and State Updates
Vue Ref Handling and Runtime Validation
New Documentation Pages and Configuration
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint install failed: lockfile failed supply-chain policy check. Run Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
🚀 Changeset Version PreviewNo changeset entries found. Merging this PR will not cause a version bump for any packages. |
|
View your CI Pipeline Execution ↗ for commit b243024
☁️ Nx Cloud last updated this comment at |
@tanstack/ai
@tanstack/ai-anthropic
@tanstack/ai-client
@tanstack/ai-code-mode
@tanstack/ai-code-mode-skills
@tanstack/ai-devtools-core
@tanstack/ai-elevenlabs
@tanstack/ai-event-client
@tanstack/ai-fal
@tanstack/ai-gemini
@tanstack/ai-grok
@tanstack/ai-groq
@tanstack/ai-isolate-cloudflare
@tanstack/ai-isolate-node
@tanstack/ai-isolate-quickjs
@tanstack/ai-ollama
@tanstack/ai-openai
@tanstack/ai-openrouter
@tanstack/ai-preact
@tanstack/ai-react
@tanstack/ai-react-ui
@tanstack/ai-solid
@tanstack/ai-solid-ui
@tanstack/ai-svelte
@tanstack/ai-utils
@tanstack/ai-vue
@tanstack/ai-vue-ui
@tanstack/openai-base
@tanstack/preact-ai-devtools
@tanstack/react-ai-devtools
@tanstack/solid-ai-devtools
commit: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Sweep across the docs to bring examples back in line with the current public surface, plus a new guide for the
createXxxOptionsfamily. Most fixes were copy-paste blockers — broken imports, fictional APIs, wrong factory signatures. Net -373 + 467 lines across 23 files; most of the additions are the new typed-options guide.Broken imports / fictional APIs removed
openai.md,gemini.md,media/text-to-speech.md,reference/functions/generateSpeech.md, plus the JSDoc onpackages/typescript/ai/src/activities/generateSpeech/index.tsso the auto-generated reference stays correct.OpenAIChatConfig/AnthropicChatConfig/GeminiChatConfig→*TextConfigin the adapter docs.createXxxChat(apiKey, config)("model")→ realcreateXxxChat(model, apiKey, config?)shape across OpenAI, Anthropic, Gemini, Ollama docs.groqSpeechremoved fromgroq.md(doesn't exist).grok.mdnow documentsgrokSpeech,grokTranscription, andgrokRealtime. Also fixed antoStreamResponsetypo totoServerSentEventsResponse.createFalImage/createFalVideoremoved fromfal.md.ollamaText(model)/createOllamaChat(model, hostOrConfig?).assertMessagesremoved fromadvanced/multimodal-content.md; replaced with a Standard-Schema (Zod) runtime validation example.toolCacheMiddlewareimports inadvanced/middleware.mdnow point at@tanstack/ai/middlewares.getting-started/overview.mdandquick-start.md.quick-start-vue.mdandapi/ai-vue.mdno longer tell users to writemessages.value/isLoading.valueinside<template>. Vue auto-unwraps refs in templates;.valueis only needed inside<script setup>. Verified againstexamples/ts-vue-chat.Tool docs
ToolCallStatelifecycle corrected to the real enum (awaiting-input,input-streaming,input-complete,approval-requested,approval-responded,complete). Replaced invented states (executing,output-available,cancelled,completed).part.argumentsis a JSON string —tool-approval.md,tool-architecture.md, andclient-tools.mdnow usepart.input(already parsed when tools are typed viaclientTools(...)) orJSON.parse(part.arguments)when not."JSON Schema infers any"→ the real behavior isunknown; Standard Schema validators (Zod, Valibot, ArkType) give full inference.Code-mode
chat({ model: "..." })field —modellives on the adapter factory.New content
docs/advanced/typed-options.md(added toconfig.jsonnav under Advanced) — covers the fullcreateXxxOptionsfamily (chat,summarize,image,audio,video,speech,transcription). Explains what they do (capture an adapter's full type so options stay narrowed when spread across modules), what they don't (no runtime behavior — identity functions), with journey-style examples for shared chat configuration and pre-configured image generation.Test plan
pnpm test:docs— 298 markdown files scanned, no broken linkspnpm build:all— all 31 packages buildpnpm --filter @tanstack/ai test:types— cleanSummary by CodeRabbit