Repository navigation
docs: rewrite the docs so you can set up each feature in a few minutes - #1843
Merged
Merged
Conversation
…inutes Rewrite every hand-written docs page in plain, friendly English. Each page starts with the problem and a short setup that runs. The deep details move to an Advanced part, or to a new advanced page next to it. - Add 23 advanced pages and their nav entries. - Correct facts that did not match the source code. - Keep page URLs and the anchors that other pages link to.
|
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configuration
You can disable this status message by setting the Use the checkbox below for a quick retry:
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 |
|
View your CI Pipeline Execution ↗ for commit 45679d6
☁️ Nx Cloud last updated this comment at |
@tanstack/ai
@tanstack/ai-acp
@tanstack/ai-angular
@tanstack/ai-anthropic
@tanstack/ai-bedrock
@tanstack/ai-byteplus
@tanstack/ai-claude-code
@tanstack/ai-client
@tanstack/ai-cloudflare
@tanstack/ai-code-mode
@tanstack/ai-code-mode-snippets
@tanstack/ai-codex
@tanstack/ai-cohere
@tanstack/ai-compaction
@tanstack/ai-computer-local
@tanstack/ai-computer-playwright
@tanstack/ai-computer-sandbox
@tanstack/ai-computer-use
@tanstack/ai-devtools-core
@tanstack/ai-durable-stream
@tanstack/ai-elevenlabs
@tanstack/ai-event-client
@tanstack/ai-fal
@tanstack/ai-gemini
@tanstack/ai-grok
@tanstack/ai-grok-build
@tanstack/ai-groq
@tanstack/ai-isolate-cloudflare
@tanstack/ai-isolate-daytona
@tanstack/ai-isolate-e2b
@tanstack/ai-isolate-node
@tanstack/ai-isolate-quickjs
@tanstack/ai-isolate-quickjs-bun
@tanstack/ai-llmgateway
@tanstack/ai-lovable
@tanstack/ai-mcp
@tanstack/ai-memory
@tanstack/ai-mistral
@tanstack/ai-octane
@tanstack/ai-ollama
@tanstack/ai-ollaya
@tanstack/ai-openai
@tanstack/ai-opencode
@tanstack/ai-openrouter
@tanstack/ai-perplexity
@tanstack/ai-persistence
@tanstack/ai-preact
@tanstack/ai-react
@tanstack/ai-reactor
@tanstack/ai-remix
@tanstack/ai-sandbox
@tanstack/ai-sandbox-blaxel
@tanstack/ai-sandbox-boxd
@tanstack/ai-sandbox-cloudflare
@tanstack/ai-sandbox-daytona
@tanstack/ai-sandbox-docker
@tanstack/ai-sandbox-e2b
@tanstack/ai-sandbox-local-process
@tanstack/ai-sandbox-railway
@tanstack/ai-sandbox-sprites
@tanstack/ai-sandbox-upstash-box
@tanstack/ai-sandbox-vercel
@tanstack/ai-skills
@tanstack/ai-solid
@tanstack/ai-svelte
@tanstack/ai-typesafe
@tanstack/ai-utils
@tanstack/ai-vercel-gateway
@tanstack/ai-vertex
@tanstack/ai-vue
@tanstack/ai-worldlabs
@tanstack/openai-base
@tanstack/preact-ai-devtools
@tanstack/react-ai-devtools
@tanstack/solid-ai-devtools
@tanstack/svelte-ai-devtools
commit: |
…/v1-rewrite # Conflicts: # docs/adapters/openai.md # docs/migration/ag-ui-compliance.md
github-actions
Bot
added
the
waiting-on: maintainer
tombeckenham
added a commit
that referenced
this pull request
Oct 22, 2026
…0.0 (#1840) * feat!: remove deprecated APIs for 1.0 Remove every deprecated export, option, field, and type alias from all packages, and the internal code that only served them. Remove old wire formats, readers for old saved data, shut-down provider models, and the @tanstack/ai-react-ui, ai-solid-ui, and ai-vue-ui packages. * docs: add the 1.0 upgrade guide and remove deprecated APIs from docs * chore: add the 1.0.0 major changeset for all packages * ci: apply automated fixes * fix(ai): read the generation input from forwardedProps The 1.0 client does not send the data copy of forwardedProps. generationParamsFromBody still required body.data, so every generation request to a route that used it failed. The envelope is now found by forwardedProps, and the input comes from forwardedProps. * fix(examples, testing): read request input from forwardedProps Server routes in the examples, the e2e app, and the panel still read body.data. The 1.0 client sends the input only in forwardedProps, so these routes now read forwardedProps and no longer fall back to data. * test(e2e): use the same client tool output schema on server and browser The server definitions of show_notification and display_chart had no outputSchema, but the browser tools had one. The schema hashes did not match, so the client treated the pause as a generic interrupt and did not resume after the tool ran. The removed pre-binding fallback hid this before. * fix(ai-vertex): use the same @google/genai copy as ai-gemini The lockfile moved the ai-vertex dev copy of @google/genai to another peer set. The vertex tests mock @google/genai, but ai-gemini loaded the other copy, so the mock did not apply and the tests failed. * docs(ai): remove container.skills from the Anthropic skill reference 1.0 removed modelOptions.container.skills, so the code block failed the kiira type check. Skills go on codeExecutionTool instead. * fix(testing): send the audio request input as the plain body The /api/audio route reads its input from forwardedProps or from the plain body. The audio page and the devtools generation hooks page still wrapped the input in { data }, so the route got no provider and failed. * chore: remove the last deprecated leftovers for 1.0 - Stop reading the 0.x interrupt reasons approval_required and client_tool_input in the stream processor. The kind comes from metadata.kind only. These reasons are no longer reserved for MCP input. - Rewrite the tests that asserted the old reason aliases. - Remove the deprecated pending alias from the useChat test titles. - Reword comments, the codemods README, the adapter skill, and CLAUDE.md that still described removed or deprecated APIs. - Move the testing panel chunk tables and sample traces to AG-UI events. - Remove the unused deprecated setHandler from the group chat example. * docs: regenerate the API reference for 1.0 This removes the pages and members of the deprecated APIs. * chore: name the removed interrupt reasons in the changeset * refactor!: remove the toolName alias from TOOL_CALL_START TOOL_CALL_START now carries the tool name only in toolCallName, the AG-UI field. The adapter extra toolName is also gone, so adapters no longer send it on TOOL_CALL_START or TOOL_CALL_END. The stream normalizer no longer copies toolName into toolCallName, and the client no longer adds toolName back on inbound chunks. * docs: regenerate the API reference without the toolName alias * test(e2e): read toolCallName on TOOL_CALL_START in the webFetch spec * docs: rewrite the docs so you can set up each feature in a few minutes (#1843) * docs: rewrite the docs so a reader can set up each feature in a few minutes Rewrite every hand-written docs page in plain, friendly English. Each page starts with the problem and a short setup that runs. The deep details move to an Advanced part, or to a new advanced page next to it. - Add 23 advanced pages and their nav entries. - Correct facts that did not match the source code. - Keep page URLs and the anchors that other pages link to. * docs: fix the code samples that failed the kiira type check * docs: rewrite the computer use pages and use gpt-6.1-sol in the samples * docs: show the interrupt flow in the tool approval diagram * docs: read toolCallName on TOOL_CALL_START in the OpenAI samples * refactor!: require threadId on chat and generation APIs threadId is now required on every chat and generation entry point. TanStack AI no longer makes a thread id for you. - Client: ChatClient, useChat and the other chat hooks, the hook that createChatHook returns, GenerationClient, VideoGenerationClient, and every generation hook in each framework. - Server: chat(), summarize(), getVideoJobStatus(), and the generation functions. TextOptions, SummarizationOptions, and ToolExecutionContext now carry a string threadId. - Remove the fallbacks that made up thread ids in core, the clients, the framework hooks, and the provider adapters. - createChatOptions() keeps threadId optional. chat() still needs it. - Remove resolveDurableThreadId and DurableThreadIdRequiredError from @tanstack/ai-sandbox. - Update tests, examples, testing apps, skills, READMEs, the migration guide, and the changeset. * docs: regenerate the API reference for required threadId * docs: pass threadId in every sample now that it is required * test: pass threadId in the Mistral test and the code mode eval * feat(ai-client)!: pass threadId to the generation fetcher * refactor(ai)!: make threadId optional on subagent bound calls * refactor!: stop making up thread ids * refactor!: take the threadId in toJsonResponse for structured output * revert: toJsonResponse does not need a threadId for structured output A structured-output response wraps the object in its own run events. Nothing resumes or saves that thread, so the caller does not pass a threadId. Keep the removed fake-text fallback and the real thread ids in the ts-react-chat server functions. * fix!: apply threadId only where it is used - getVideoJobStatus(): threadId is optional again. Only middleware reads it. Plain status polls in docs, READMEs, the skill, and apps drop it. - createComputerUse: a call with no threadId uses the fixed 'computer-use:shared' thread again. - @tanstack/ai-sandbox: the tool bridge and executeHostTool() take a required threadId and put it in each tool context. The harness adapters and the Cloudflare coordinators pass the run's thread id. - ChatClient passes its threadId to client tool execution. - Code Mode bindings always get a context. The threadId comes from the parent context. A tool gets no context when there is no threadId. - Compaction and snippet selection run their internal chat() calls on `${threadId}:compaction` and `${threadId}:snippets`. - Connection adapters: the run context is a required fourth argument of connect() and send(). The runtime error stays for untyped callers. * docs: regenerate the API reference for getVideoJobStatus * fix(ai)!: ToolExecutionContext.threadId is optional outside a chat registerWebMCPTools and the ai-mcp server run tools with no chat, so there is no thread id. Every chat path still sets it: chat(), ChatClient client tools, the sandbox bridges, and the Code Mode bindings. - Code Mode bindings use ToolExecutionContext again. ToolBindingContext is gone, and a tool always gets the binding context. - Docs say when threadId is missing. * docs: regenerate the API reference for ToolExecutionContext.threadId * docs: pass threadId in samples that kiira could not check Samples that pass a value from a relative import (./tools) into chat() or createChatClientOptions() were not type-checked in full: kiira hides the unresolved-import error, and TypeScript then drops every other error in that call. Add the missing threadId, drop the removed useChat id option, and fix the ag-ui-compliance prose that said the runtime makes a thread id. Also correct the kiira snippet lesson, which called the binding a usable any. * fix: reject 0.x Cloudflare run records and wire byok in Octane useChat - ai-sandbox-cloudflare: a rec: value in the 0.x layout (done/error status) now throws a clear "migrate first" error. Read as-is it looked like a live run, and the stall watchdog marked finished runs failed. list() skips such records with a log line, so one old record cannot stop the watchdog for live runs. - ai-octane: useChat passes byok and byokProvider to ChatClient, like the other framework hooks. The option was typed but dropped. - ai-mistral, ai-octane: published dependencies use workspace:^, so 1.0 does not pin ai-utils and ai-client to an exact version. - ai-solid: the README was a copy of the React one. Rewrite it for Solid and 1.0 (threadId, interrupts). Co-Authored-By: Claude <noreply@anthropic.com> * docs: fix 1.0 samples and claims found in the full PR review - Pass threadId in every sample and JSDoc @example that calls chat(), summarize(), a generate* function, a client, or a hook. Regenerate docs/reference. - Server samples read the 1.0 request: generationParamsFromRequest and forwardedProps, not a top-level prompt or body.data. Custom transport samples forward runContext instead of making ids up. - Fix samples that ran but did the wrong thing: Claude Code and Codex session resume, generation runId, the hardcoded video thread, the aborted status, shared 'thread-1' helpers in skills, the Svelte quick-start submit, apply-answers, the subagents tutorial. - Correct claims the code does not support: sandbox policy, tool bridge host, sandbox key, harness tool checks, Gemini structured streaming, WebSocket resume, mcp-input reasons, openai-compatible features, OpenAI sampling params, the 0.x Cloudflare run-log migration, blobKey. - Fix stale comments that named removed APIs. Co-Authored-By: Claude <noreply@anthropic.com> * docs: define persistence and sandbox inline so kiira checks the calls The video persistence route and the harness structured-output skill sample imported persistence and sandbox from relative modules. kiira hides the unresolved import, and TypeScript then drops every other error in the call that uses the value. Build both values in the same fence. Co-Authored-By: Claude <noreply@anthropic.com> * fix(ai-sandbox): refuse needsApproval tools in the harness tool bridge The bridge called execute() directly, so a needsApproval tool ran with no approval through every harness adapter. It cannot pause for an approval round-trip, so fail fast with a clear error, as the docs already state. Closes #1854 * test(ai-vertex): dedupe @google/genai so the factory mock applies pnpm resolves two copies of @google/genai 2.10.0, one per zod peer (4.3.6 for ai-gemini, 4.6.5 for ai-vertex). The vertex tests mock the copy ai-vertex sees, but ai-gemini constructs GoogleGenAI from its own, so the mock did not apply and factories.test.ts failed. f568fef fixed this by hand-editing the lockfile, and the next pnpm install undid it. resolve.dedupe in the test config loads one copy, whatever pnpm picks. Co-Authored-By: Claude <noreply@anthropic.com> * feat(ai-client)!: pass the AG-UI RunAgentInput to stream() and rpcStream() The factory got only (messages, data, abortSignal), so a server function could not read the client's runId or interrupt resume, and every caller passed threadId a second time by hand. The run context was dropped on purpose in #511, when ids were made up if missing; 1.0 requires them. - The factory gets the run's AG-UI RunAgentInput as a 4th argument: the same body the HTTP adapters POST. A server reads it with chatParamsFromRequestBody() or generationParamsFromBody(). - RunAgentInput is re-exported as a type from @tanstack/ai/client. - data and abortSignal are typed `| undefined` so input can be required. A factory that takes fewer parameters still type-checks. - Docs, the custom-backend skill, and JSDoc send input instead of a hand-passed threadId. Co-Authored-By: Claude <noreply@anthropic.com> * docs: start each guide with the call, not a scene * chore(skills): open docs pages with the call, said once The docs skill told pages to open with the reader's problem as a short scene. The docs now open with the call and what the reader gets, which answers "is this my page?" in one line. Encode that, and add the rule the rewrite missed on some pages: the opener is said once, so the next paragraph starts the steps or adds a new fact. Co-Authored-By: Claude <noreply@anthropic.com> * docs: say each page opener once The call-first openers landed above the old intro paragraphs, so 42 pages repeated the opener, kept a "X fixes this." line whose problem was cut, or kept a broken "createChatHook from ..." fragment (all eight UI framework pages). Remove the repeats and orphaned lines, keep each new fact as one sentence, and fix the fragments. Openers are unchanged. Co-Authored-By: Claude <noreply@anthropic.com> * fix!: fail loudly on a missing threadId and on 0.x saved data - chat(), ChatClient, GenerationClient and VideoGenerationClient throw a clear error when threadId is missing or empty. The type already required it; a JS caller got persistence keyed "undefined" and runs with no thread. Drops two guards that could no longer fire. - A 0.x bare UIMessage[] in client persistence logs an error and is not overwritten by the next save, so the history is not lost. - retrieveBlob throws a clear error for a 0.x artifact record with no blobKey, instead of a misleading not-found. - A 0.x unbound tool interrupt record logs a warning that it stays pending. - A client tool or approval interrupt whose server and client schemas differ logs a warning naming the tool before it falls back to a generic interrupt. Co-Authored-By: Claude <noreply@anthropic.com> * refactor(ai)!: require threadId and runId in generation params GenerationParams typed threadId and runId as optional and the parser also took a bare input body, a 0.x shape with no ids. 1.0 generation functions need a threadId, so every route repeated an `if (!threadId) return 400` check. AG-UI RunAgentInput requires both ids, and chatParamsFromRequestBody already does. - generationParamsFromBody reads only the envelope and throws when threadId or runId is missing or empty. Drops the bare-input branches and three helpers. - Remove the per-route threadId checks and optional runId spreads from docs, the media-generation skill, and the examples. Co-Authored-By: Claude <noreply@anthropic.com> * test: pass threadId where chat() and the clients now require it 69a3bbe made chat(), ChatClient, GenerationClient and VideoGenerationClient throw at runtime on a missing threadId. Tests that called them without one now failed, and tests that checked the "connection or fetcher" error hit the threadId error first. Pass a threadId so each test reaches the case it is about. Co-Authored-By: Claude <noreply@anthropic.com> * refactor: remove dead fallbacks and copies left by required threadId - ai-client devtools: the bridge threadId is required, so drop withLiveClientIdentity, the `?? ''` fallbacks, the always-true branch, and the `const client = this` getters in the three clients. - ai-client: drop the restoreInboundUsage alias and a `?? {}` on a spread. - Framework generation hooks: drop the `Omit<..., 'persistence' | 'threadId'> & GenerationPersistenceOptions` that re-added what it removed (43 signatures), and the persistenceProps temporary in 8 files. - ai-react: delete tool-result-content.ts; its only caller was deleted. - ai: one WithOptionalThreadId type, reused by BoundTextActivityOptions, bound calls, and createChatOptions, which reuses BoundTextActivityOptions instead of a copy. Drop the 0.x nested RUN_ERROR copy in normalizeStreamChunk. - ai-persistence: artifactBlobKey is a local function in middleware.ts; simplify the resume guard. Co-Authored-By: Claude <noreply@anthropic.com> * test(e2e): type-check the specs and fix what that found testing/e2e/tsconfig.json only included src/, so tsc never saw tests/. Include it and fix the 20 errors with narrowing and real types, no casts: - multi-turn-reasoning never ran: a stale-branch squash merge (98979f7) dropped the feature from the E2E registry, so the spec matched no providers. Restore it for Anthropic. - delivery-durability: "a second tab joins an existing run" parsed the producing tab's output but never compared it. Assert both tabs match. - web-mcp-tools: the local registration type required `options`, which Chrome does not pass. Make it optional. - getMessages() returns UIMessage[] instead of any[]; narrow the reads that exposed. Type guards for tool-call events, typed fixtures. Co-Authored-By: Claude <noreply@anthropic.com> * fix(ai-client): match the WebMCP execute type to what Chrome and the code pass Chrome calls a registered WebMCP tool's execute(input) with no options, and the function TanStack AI registers already takes optional options. The internal WebMCPTool interface required them. Co-Authored-By: Claude <noreply@anthropic.com> * test: type-check the Octane tests, remix example tests, and e2e setup - ai-octane: include tests/ in the type check. Type the chat-ui test callbacks with the real ai-client UI types, add a declaration for the SSR fixture, and resolve @octanejs/testing-library subpaths through a tsconfig paths entry that mirrors the vite alias. Fix two test bugs: "preserves unrelated caller metadata" passed a field the hook does not accept, and a TEXT_MESSAGE_CONTENT event carried a `content` field. - ts-remix-chat: type-check its tests; build the test router with the render middleware the app's RouterTypes expects. - e2e: type-check the Playwright config and global setup/teardown. Drop a `duration` field aimock never reads, and type the aimock global instead of casting globalThis. - ts-solid-chat: delete three files nothing imported. Co-Authored-By: Claude <noreply@anthropic.com> * chore: upgrade oxlint to 1.89 and oxlint-tsgolint to 7.0.2004 The repo was on oxlint-tsgolint 0.24, the pre-TypeScript-7 line, and `^0.24.0` can never reach 7.x. oxlint 1.89 requires oxlint-tsgolint >= 7.0.2003. Bump oxlint, oxlint-plugin-eslint and oxlint-tsgolint together. The only new finding across all 76 linted projects: a zero-width space in an ai-skills doc comment, used to break up `**/`. Write the path as `skills/<name>/SKILL.md` instead. Co-Authored-By: Claude <noreply@anthropic.com> * fix(ai-octane): make the published ui types match the .tsrx source The hand-written create-ui and create-chat-hook .tsrx.d.ts files had drifted to ComponentBody<any> and loose prop shapes. Replace them with the real declaration emit, export the part and interrupt mixin types, drop the hand-copied test aliases, and add a typetest that fails if the declarations loosen again. The docs sample now uses ToolProps directly. * chore(skills): docs skill states readers and tone instead of asking * docs: merge the Vercel AI SDK comparison into one page * docs: drop the agent class and RSC reasons from the AI SDK comparison * docs: point missing providers to a request or the adapter guide * docs: put TanStack AI first in the AI SDK API map * Revert "docs: put TanStack AI first in the AI SDK API map" This reverts commit 82aad9d. * docs: put the Vercel AI SDK first in the comparison table * ci: apply automated fixes * test(ai): pass threadId in the activity middleware test from main --------- Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com> Co-authored-by: Tom Beckenham <34339192+tombeckenham@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com>
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
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.
Review this PR after #1840, because it targets that branch. It rewrites every hand-written docs page in plain, friendly English. Each page now opens with the problem and a setup you can copy and run in a few minutes. The deep details are in an Advanced part at the end, or on a new advanced page next to it.
🎯 Changes
Who each page is for. The plan has five readers: the first-timer, the feature builder, the provider picker, the production developer, and the upgrader. Each page has a path for its reader:
src.migration/v1.mdis a 5-step upgrade with a done check.New pages. 23
*-advanced.mdpages hold the deep details that moved off the entry pages. Each one is indocs/config.json, right after its parent page.Facts corrected from the source code. The writers checked samples and claims against
packages/*/src. The biggest corrections:withSandbox), and many documented options did not exist.resumeandparentRunId, so those flows did not resume.store-reference.mdlisted 7 store keys. There are 8.URLs did not change. Headings that other pages link to kept their text.
docs/reference/(TypeDoc output) is not touched.✅ Checklist
pnpm run test:pr, or these tests do not apply to this pull request.docs/for this change, or this change is not user-facing.pnpm changeset), or this PR does not change a published package.🚀 Release Impact
Testing
Commands run (all pass):
pnpm test:docs: no broken links in 877 markdown files.pnpm test:kiira: 1802 of 1802 code samples type-check (286 markedignore, for example.vue,.svelte, and fences that need a generated route tree).×,·): no hits.I did not run
pnpm test:pr. This PR changes only files underdocs/, so CI runs the rest.Manual test:
docs/getting-started/quick-start.mdand follow the 4 steps in a new Next.js app. A streaming chat works.docs/tools/tools.md, and run its quick setup. One server tool runs in 3 steps.docs/adapters/openai.mdanddocs/adapters/groq.md. The sections are in the same order.How this PR makes testing easy: every code sample is type-checked by
kiirain CI, so a sample that does not match the API fails the build.Risk / rollback
Low risk. Only docs change. External links to a moved anchor (for example a deep link to an OpenAI provider tool) now land at the top of the page and not at that section. The section is on the new
-advancedpage. To undo, revert this PR.Found while writing (not fixed here)
These are code issues, not docs. Each one needs its own PR:
max_tokensfor Grok, but Grok needsmax_output_tokens(codemods/move-sampling-to-model-options/transform.ts).exposePreviewToolfinds the container bythreadId, butcloudflareSandboxnames it with the hashed sandbox key.resolvePreviewHostthrows on*.workers.devwhenPREVIEW_HOSTNAMEis not set.outputSchema. The upgrade guide now says so.