fix(skills, ui-registry): add @tiptap/extensions dep and fix path alias guidance

[akhileshrangani4]

Summary

• Add @tiptap/extensions to message-input config.json (needed by @tiptap/extension-placeholder)
• Fix path alias guidance to check all projects for @/*, not just Vite (Cal.com uses custom aliases)
• Add chat UI layout options table (collapsible vs panel vs full) to Step 6
• Use generic component names in keyboard/z-index examples instead of hardcoding MessageThreadCollapsible
• Add Suggestion type definition and initialSuggestions usage to threads reference (both skills)
• Add dynamic tool registration pattern (registerTool + useEffect + useRef guard) to tools reference
• Add cache invalidation after mutations pattern to tools reference
• Add null stripping guidance for tool inputs
• Sync both skills' reference docs to be identical

Why

Follow-up to #2650. Found while integrating Tambo into Cal.com (34k stars, Next.js + Tailwind + tRPC):

• @tiptap/extension-placeholder imports from @tiptap/extensions which wasn't in the dep list (TAM-1355)
• Cal.com's tsconfig uses ~/* and @components/* instead of @/*, so Tambo components failed to resolve
• Skill hardcoded message-thread-collapsible but Cal.com needed message-thread-panel for its sidebar layout
• Using label/prompt for initialSuggestions produced empty pills (actual type uses title/detailedSuggestion)
• registerTool() requires outputSchema (unlike defineTool()) but this wasn't documented
• AI sends null for optional fields which tRPC rejects
• After mutations, host app UI doesn't update without cache invalidation
• The defineTool + TamboProvider tools=[] pattern doesn't work when tools need access to the host app's API client (tRPC). The registerTool + useEffect pattern is the right approach but wasn't documented.

All patterns match how the Tambo web app itself does tool registration (apps/web/lib/tambo/tools/).

Test plan

• Run tambo add message-thread-collapsible --yes and verify @tiptap/extensions resolves
• Verify threads reference documents correct Suggestion type (id, title, detailedSuggestion, messageId)
• Verify tools reference shows registerTool pattern with useRef guard, cache invalidation, and null stripping
• Confirm both skills' reference docs are identical for shared sections

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
cloud	Ignored	Preview	Mar 20, 2026 9:50pm
showcase	Ignored	Preview	Mar 20, 2026 9:50pm
tambo-docs	Ignored	Preview	Mar 20, 2026 9:50pm

[pullfrog]

Clean, well-scoped fix. Both changes are correct:

1. @tiptap/extensions dep: Confirmed via npm registry that @tiptap/extension-placeholder@3.20.4 declares @tiptap/extensions as a peer dependency — consumer projects must install it explicitly. The addition is correctly placed in alphabetical order.

2. Path alias guidance: The old text incorrectly assumed all Next.js projects have @/* configured. The rewrite properly instructs agents to check first and provides clear guidance for adding the alias when missing, with a sensible note about ["./*"] for projects without src/. Restructuring tsconfig guidance before the Vite-specific section is the right call since it applies universally.

  ^{｜ View workflow run ｜ pullfrog.com ｜ 𝕏}

[pullfrog]

TL;DR — Fixes integration issues found while adding Tambo to Cal.com: adds the missing @tiptap/extensions peer dependency, overhauls the build-with-tambo skill's Step 6 to cover all three chat layouts with framework-agnostic path-alias guidance, documents the Suggestion type and initialSuggestions prop, and adds patterns for dynamic tool registration, cache invalidation, and null stripping to the tools reference.

Key changes

• Add @tiptap/extensions to message-input dependency list — @tiptap/extension-placeholder imports from this package at runtime, but it was missing from config.json, causing resolution errors on tambo add.
• Broaden @/* path-alias guidance in SKILL.md — the skill now tells the agent to check whether @/* exists in the project's tsconfig before assuming it does, and provides framework-agnostic instructions with a Vite-specific addendum.
• Add chat UI layout comparison table — Step 6 now presents message-thread-collapsible, message-thread-panel, and message-thread-full in a table with guidance on when to use each, instead of hardcoding the collapsible variant.
• Use generic component names in keyboard/z-index examples — code snippets for keyboard event isolation and z-index layering now include comments noting to swap in whichever component was installed.
• Document Suggestion type and initialSuggestions prop — both skills' threads references now include the Suggestion interface definition and a usage example for passing starter suggestions to chat components.
• Add dynamic registerTool pattern to tools reference — documents using registerTool() inside a useEffect with a useRef guard for apps that need access to host API clients (tRPC, GraphQL) via hooks, instead of module-level defineTool().
• Add cache invalidation and null-stripping guidance — tools reference now covers invalidating query caches after mutations and stripping null values the AI sends for optional fields.
• Sync generative-ui tools reference — the generative-ui skill's tools-and-context.md now mirrors building-with-tambo's version with all new patterns.

_{Summary ｜ 6 files ｜ 6 commits ｜ base: main ← avi/fix-tiptap-extensions-and-path-alias}

Missing @tiptap/extensions peer dependency

Before: @tiptap/extensions was not listed in the message-input config.json, so tambo add message-thread-collapsible could fail when @tiptap/extension-placeholder tried to resolve it.
After: The package is included in the dependency array alongside the other tiptap packages.

packages/ui-registry/src/components/message-input/config.json

Framework-agnostic path-alias guidance

Before: The skill assumed Next.js projects already have @/* configured and only showed the alias setup for Vite. Projects like Cal.com (which use ~/* and @components/* instead) would fail to resolve Tambo component imports.
After: The skill instructs the agent to check for @/* in any project's tsconfig first, provides a universal tsconfig snippet (with a src/ vs root distinction), and moves the Vite-specific vite.config.ts alias into a clearly scoped subsection.

Why was the original assumption wrong?

create-next-app does set up @/* by default, but many real-world Next.js codebases override or remove that alias. Hardcoding "Next.js already has it" caused the agent to skip a necessary configuration step.

plugins/tambo/skills/building-with-tambo/SKILL.md

Chat UI layout options table and generic examples in Step 6

Before: Step 6 hardcoded message-thread-collapsible as the only tambo add example, and the keyboard/z-index code snippets referenced only MessageThreadCollapsible.
After: A comparison table shows collapsible (floating overlay), panel (sidebar), and full (full-page) with guidance on when to use each. Code examples now include inline comments reminding the developer to swap in whichever component they installed.

plugins/tambo/skills/building-with-tambo/SKILL.md

Suggestion type and initialSuggestions documentation

Before: The threads reference had no documentation for the Suggestion type or how to pass starter suggestions to chat components.
After: Both the building-with-tambo and generative-ui threads references document the Suggestion interface fields (id, title, detailedSuggestion, messageId) and show how to use the initialSuggestions prop with MessageThreadPanel.

Initial suggestions only appear when the thread has no messages — once the user sends a message, they're replaced by AI-generated suggestions.

plugins/tambo/skills/building-with-tambo/references/threads.md · plugins/tambo/skills/generative-ui/references/threads.md

Dynamic tool registration with registerTool

Before: The tools reference only documented defineTool() at module level. Integrations needing access to host app hooks (e.g. tRPC's useUtils()) had no documented pattern.
After: A new section shows the registerTool() + useEffect + useRef guard pattern — call registerTool from inside a component where hooks are available, with a ref to prevent re-registration on every render.

The pattern accepts the API client and cache utils as arguments, keeping tools testable and decoupled from React. This matches how the Tambo web app itself registers tools in apps/web/lib/tambo/tools/.

plugins/tambo/skills/building-with-tambo/references/tools-and-context.md · plugins/tambo/skills/generative-ui/references/tools-and-context.md

Cache invalidation and null stripping for tool inputs

Before: No guidance on what happens after a tool mutates data, or how to handle null values the AI sends for optional fields.
After: The tools reference documents calling utils.{router}.invalidate() after mutations so the host app's UI refreshes, and provides a one-liner Object.fromEntries filter to strip nulls before passing inputs to APIs like tRPC that reject them.

plugins/tambo/skills/building-with-tambo/references/tools-and-context.md · plugins/tambo/skills/generative-ui/references/tools-and-context.md

  ^{｜ View workflow run ｜ Triggered by Pullfrog ｜ pullfrog.com ｜ 𝕏}

[charliecreates]

Non-blocking feedback (1)

1. Align follow-on examples with the selected chat component — .../building-with-tambo/SKILL.md#L244
   Step 6 now defaults to message-thread-panel, but the keyboard-isolation and z-index snippets later in the file still hardcode <MessageThreadCollapsible />.
   For readers who follow the default command, that creates an easy copy/paste mismatch between the installed component and the example JSX. Consider a neutral placeholder (for example, <SelectedMessageThread />) or a short note telling readers to swap in the component they installed.

If you'd like me to push fixes, reply with item numbers (for example: please fix 1).