Tavus CVI Component Library

A CLI tool for installing and managing CVI (Conversational Video Interface) components for React applications. This library provides pre-built components for creating real-time multimodal video conversations with AI replicas.

Quick Start

Initialize the project:

npx @tavus/cvi-ui@latest init

This will:

• Create a cvi-components.json configuration file
• Prompt for TypeScript preference
• Install the necessary dependencies

Add components to your project:

npx @tavus/cvi-ui@latest add conversation

Wrap your app with the CVI provider:

import { CVIProvider } from './components/cvi/components/cvi-provider';

function App() {
	return <CVIProvider>{/* Your app content */}</CVIProvider>;
}

Add conversation components:

import { Conversation } from './components/cvi/components/conversation';

function CVI() {
	return (
		<div
			style={{
				width: '100%',
				height: '100%',
				maxWidth: '1200px',
				margin: '0 auto',
			}}
		>
			<Conversation conversationUrl="YOUR_TAVUS_MEETING_URL" onLeave={() => {}} />
		</div>
	);
}

(Optional) Install the server-side conversation lifecycle:

npx @tavus/cvi-ui@latest add tavus-api

Detects your framework (Next.js / Remix / TanStack Start) and installs a server route that creates and ends Tavus conversations using your TAVUS_API_KEY — kept on the server. Use createTavusConversation() from your UI to obtain the conversation_url you pass into <Conversation /> above. See Conversation lifecycle below for the Vite-with-server opt-in.

Conversation lifecycle (creating & ending calls)

To open a conversation you need a conversation_url. Tavus issues those via its REST API — and that API requires your TAVUS_API_KEY. The key must never ship in your client bundle. The CLI installs the right pieces for your framework so the key stays on the server:

npx @tavus/cvi-ui@latest add tavus-api

| Detected framework | What gets installed | | ----------------------------------- | --------------------------------------------------------------- | | Next.js (App Router) | app/api/tavus/route.ts + lib/tavus-client.ts | | Next.js (Pages Router) | pages/api/tavus.ts + lib/tavus-client.ts | | Remix | app/routes/api.tavus.ts + lib/tavus-client.ts | | TanStack Start | app/routes/api/tavus.ts + lib/tavus-client.ts | | Anything else (plain Vite, Expo, …) | Exits with an error. See the Vite-with-server opt-in below. |

Set the server-side env var (no client prefix). Create your API key in the Tavus Developer Portal →

TAVUS_API_KEY=sk_...

Then call from your UI — your key is never touched on the client:

import { createTavusConversation, endTavusConversation } from './components/cvi/lib/tavus-client';

const { conversation_id, conversation_url } = await createTavusConversation({
	replica_id: 'rf4e9d9790f0',
	persona_id: 'pcb7a34da5fe',
});
// …pass conversation_url into <Conversation />, then later:
await endTavusConversation(conversation_id);

createTavusConversation() accepts every field on POST /v2/conversations — see the create-conversation API reference for the full schema. Unknown fields are forwarded as-is, so new Tavus fields work without a CLI update.

Vite (or any setup) with a server runtime

If you're on Vite + a server (Vinxi, Hono, vike-server, custom Express, Bun, Cloudflare Workers, …), opt in to a runtime-agnostic handler:

npx @tavus/cvi-ui@latest add tavus-api-vite-ssr

That installs lib/tavus-api-vite-ssr.ts exporting handleTavusRequest(request: Request): Promise<Response> — wire it into your middleware. The file header has examples for Hono, h3/Vinxi, and Express + a Web Fetch adapter. The matching lib/tavus-client.ts is installed alongside, so once you mount the handler at POST /api/tavus, the existing browser code Just Works.

No client-only mode. We deliberately do not ship a browser-direct client. Calling Tavus directly from the browser would put your API key in the bundle, which is unsafe in any deployed context.

Documentation

• CVI Documentation

Examples

• Tavus Examples

License

MIT License - see the LICENSE file for details.