@vercel/v0

Official v0 SDK for programmatic access to v0.app.

Installation

npm install @vercel/v0
# or
pnpm add @vercel/v0
# or
yarn add @vercel/v0

Usage

Basic Example

import { createV0Client } from '@vercel/v0'

const client = createV0Client({
  token: process.env.V0_API_TOKEN!,
})

// Stream a message to v0
for await (const event of client.message.createStream({
  message: 'Create a landing page with a hero section',
})) {
  switch (event.type) {
    case 'start':
      console.log('Started chat:', event.chatId)
      break
    case 'message':
      console.log('Message update received')
      break
    case 'complete':
      console.log('Generation complete!')
      break
    case 'error':
      console.error('Error:', event.error)
      break
  }
}

Git Operations

// Push changes to a branch
const pushResult = await client.git.branch.push({
  chatId: 'chat_123',
})

// Create a pull request
const prResult = await client.git.pullRequest.create({
  chatId: 'chat_123',
  content: {
    title: 'Add new landing page',
    body: 'This PR adds a new landing page with a hero section.',
  },
})

if (prResult.ok) {
  console.log('PR created:', prResult.value.htmlUrl)
}

// Check deployment status
const status = await client.git.deploymentStatus.get({
  chatId: 'chat_123',
})

if (status.ok) {
  console.log('Deployment status:', status.value.status)
}

Sandbox Configuration

// Use with a GitHub repository
for await (const event of client.message.createStream({
  message: 'Add a dark mode toggle',
  sandbox: {
    source: { type: 'git', org: 'myorg', repo: 'myrepo' },
    branch: { mode: 'auto', prefix: 'v0/' },
  },
})) {
  // Handle events...
}

// Use with a Vercel project
for await (const event of client.message.createStream({
  message: 'Update the header component',
  sandbox: {
    source: { type: 'vercel', projectId: 'prj_123' },
    branch: { mode: 'explicit', name: 'feature/header-update' },
  },
})) {
  // Handle events...
}

API Reference

createV0Client(options)

Creates a new v0 client instance.

Options

• token (required): Your v0 API token. Can be a string or an async function that returns a token.
• baseUrl (optional): Custom base URL. Defaults to https://v0.app.
• headers (optional): Custom headers to include in requests.

Client Methods

client.message.createStream(input)

Creates a streaming message to v0. Returns an async generator of StreamEvent.

client.git.branch.push(input)

Pushes changes to a branch.

client.git.pullRequest.create(input)

Creates a pull request with the generated changes.

client.git.deploymentStatus.get(input)

Gets the deployment status for a chat.

Types

All types are exported from the package:

import type {
  V0ClientOptions,
  StreamEvent,
  CreateStreamInput,
  SandboxConfig,
  RemoteConfig,
  MCPTool,
  CreatePullRequestInput,
  CreatePullRequestResult,
  PushToBranchInput,
  PushToBranchResult,
  GetDeploymentStatusInput,
  GetDeploymentStatusResult,
  DeploymentStatus,
  ProgrammaticFlags,
  ComposedProgrammaticResult,
} from '@vercel/v0'

License

MIT