Installation

This guide provides comprehensive installation instructions for the Vercel AI Chatbot, including all prerequisites, dependencies, and configuration steps.

System requirements

Before installing the chatbot, ensure your system meets these requirements:

Required software

Node.js

Minimum version: 18.18.0 or higherRecommended: Node.js 20.x LTS or 22.xThe chatbot uses modern JavaScript features and Next.js 16, which require Node.js 18+.Check your version:

node --version

Install or update Node.js:

macOS/Linux: Use nvm
```
nvm install 20
nvm use 20
```
Windows: Download from nodejs.org

Using package managers:

# macOS with Homebrew
brew install node@20

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

pnpm

Required version: 9.12.3 (specified in package.json)Why pnpm? This project uses pnpm for:

Faster installs with content-addressable storage
Strict dependency resolution
Efficient disk space usage
Better monorepo support

Install pnpm:

# Using npm
npm install -g [email protected]

# Using Homebrew (macOS)
brew install pnpm

# Using standalone script (Linux/macOS)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Using PowerShell (Windows)
iwr https://get.pnpm.io/install.ps1 -useb | iex

Verify installation:

pnpm --version
# Should output: 9.12.3 or higher

While npm and yarn will work, using pnpm ensures compatibility with the project’s lock file (pnpm-lock.yaml).

Git

Minimum version: 2.xRequired for cloning the repository and version control.Check your version:

git --version

Install Git:

macOS: brew install git or use Xcode Command Line Tools
Linux: sudo apt-get install git or sudo yum install git
Windows: Download from git-scm.com

Cloud services

The chatbot requires these Vercel services:

Service	Purpose	Required	Documentation
AI Gateway	LLM access (GPT-4, Claude, Gemini)	Yes	vercel.com/ai-gateway
Postgres	Database for chats, users, documents	Yes	vercel.com/docs/postgres
Blob Storage	File uploads and attachments	Yes	vercel.com/docs/vercel-blob
Redis	Caching and rate limiting	Optional	vercel.com/docs/redis

All Vercel services offer generous free tiers. You can start development without any cost.

Installation steps

1. Clone the repository

Clone the chatbot from GitHub:

git clone https://github.com/vercel/openchat.git
cd openchat

Alternative: Fork the repository first if you plan to customize and deploy your own version:

Go to github.com/vercel/openchat
Click Fork in the top right

Clone your fork:

git clone https://github.com/YOUR_USERNAME/openchat.git
cd openchat

2. Install dependencies

Install all Node.js packages:

pnpm install

This installs all dependencies defined in package.json:

Core dependencies (20+ packages)

next (16.0.10) - React framework with App Router
react (19.0.1) & react-dom - UI library
ai (6.0.37) - Vercel AI SDK for LLM integration
@ai-sdk/react - React hooks for AI interactions
@ai-sdk/gateway - Multi-provider AI Gateway client
next-auth (5.0.0-beta.25) - Authentication
drizzle-orm (0.34.0) - TypeScript ORM
postgres (3.4.4) - PostgreSQL client

UI dependencies (30+ packages)

@radix-ui/react-* - Accessible UI primitives
tailwindcss (4.1.13) - Utility-first CSS
framer-motion - Animation library
lucide-react - Icon library
shadcn/ui components
codemirror - Code editor
prosemirror - Rich text editor

Storage & utilities (40+ packages)

@vercel/blob - File storage client
@vercel/analytics - Analytics integration
redis - Caching client
bcrypt-ts - Password hashing
zod - Schema validation
date-fns - Date utilities
nanoid - ID generation

Development dependencies (15+ packages)

typescript (5.6.3) - Type checking
drizzle-kit (0.25.0) - Database migrations
@playwright/test - E2E testing
ultracite (7.0.11) - Linting and formatting
tsx - TypeScript execution
@biomejs/biome - Fast formatter

The installation downloads 90+ packages and may take 2-5 minutes. Ensure you have a stable internet connection.

3. Configure environment variables

Create your environment configuration file:

cp .env.example .env.local

Edit .env.local with your credentials:

# Authentication Secret
# Generate at: https://generate-secret.vercel.app/32
# Or run: openssl rand -base64 32
AUTH_SECRET=your_32_character_secret_here

# AI Gateway API Key
# Create at: https://vercel.com/ai-gateway
# NOTE: Not required for Vercel deployments (uses OIDC tokens)
AI_GATEWAY_API_KEY=vg_xxxxxxxxxxxxxxxx

# Vercel Blob Storage
# Create at: https://vercel.com/docs/vercel-blob
BLOB_READ_WRITE_TOKEN=vercel_blob_rw_xxxxxxxxxxxxxxxx

# PostgreSQL Database
# Create at: https://vercel.com/docs/postgres
# Format: postgres://user:password@host:port/database?sslmode=require
POSTGRES_URL=postgres://default:[email protected]:5432/verceldb

# Redis (Optional)
# Create at: https://vercel.com/docs/redis
REDIS_URL=redis://default:[email protected]:6379

Detailed environment variable setup

Generate AUTH_SECRET

Create a secure random secret for session encryption:

# Option 1: Online generator
open https://generate-secret.vercel.app/32

# Option 2: OpenSSL
openssl rand -base64 32

# Option 3: Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Copy the output and set it as AUTH_SECRET in .env.local.

Set up AI Gateway

Go to vercel.com/ai-gateway
Click Create API Key
Name it (e.g., “Chatbot Development”)
Copy the key (starts with vg_)
Set as AI_GATEWAY_API_KEY in .env.local

Vercel deployments: If deploying to Vercel, you can skip this step. The platform uses OIDC tokens automatically.

Create Postgres database

Go to your Vercel dashboard
Select your project (or create a new one)
Navigate to Storage → Create Database
Select Postgres
Copy the POSTGRES_URL connection string
Set it in .env.local

Use the Pooled Connection string for better performance with serverless functions.

Set up Blob storage

In Vercel dashboard, go to Storage
Click Create Database → Blob
Name your store (e.g., “chatbot-files”)
Copy the BLOB_READ_WRITE_TOKEN
Set it in .env.local

Configure Redis (optional)

Redis improves performance with caching and rate limiting:

In Vercel dashboard, go to Storage
Click Create Database → Redis
Copy the REDIS_URL
Set it in .env.local

Redis is optional. The chatbot will work without it, but you’ll miss out on caching benefits.

4. Set up the database

Run database migrations to create all required tables:

pnpm db:migrate

What this does:

Reads your POSTGRES_URL from .env.local
Connects to the database
Executes migration files from lib/db/migrations/
Creates tables: users, chats, messages, documents, votes, suggestions
Sets up indexes and constraints

Expected output:

⏳ Running migrations...
✅ Migrations completed in 234 ms

Migration failed? Common issues:

POSTGRES_URL not set or incorrect
Database not accessible (firewall/network)
Insufficient permissions
Database already has conflicting tables

Alternative: Manual database setup

If migrations fail, you can use Drizzle Kit directly:

# Generate migration files
pnpm db:generate

# Push schema directly to database (skip migrations)
pnpm db:push

# View database in Drizzle Studio
pnpm db:studio

5. Verify installation

Start the development server to verify everything works:

pnpm dev

You should see:

▲ Next.js 16.0.10 (turbo)
- Local:        http://localhost:3000
- Environments: .env.local

✓ Ready in 1.2s

Open http://localhost:3000 in your browser.

Troubleshooting

pnpm: command not found

Problem: pnpm is not installed or not in PATH.Solution:

# Install pnpm globally
npm install -g [email protected]

# Or use npx (no installation needed)
npx pnpm install
npx pnpm dev

Node version error

Problem: Error: The engine "node" is incompatible with this moduleSolution:

# Check current version
node --version

# Upgrade to Node.js 20+
nvm install 20
nvm use 20

# Re-install dependencies
rm -rf node_modules
pnpm install

Database migration fails

Problem: Migrations fail with connection or permission errors.Solutions:

Check connection string:

# Verify POSTGRES_URL is set
echo $POSTGRES_URL

# Test connection
psql $POSTGRES_URL -c "SELECT version();"

Use Drizzle Studio to inspect:

pnpm db:studio
# Opens https://local.drizzle.studio

Reset and retry:

# Drop all tables (⚠️ destroys data)
pnpm db:drop

# Re-run migrations
pnpm db:migrate

Module not found errors

Problem: Cannot find module '@radix-ui/...' or similar.Solution:

# Clear pnpm cache
pnpm store prune

# Delete node_modules and lock file
rm -rf node_modules pnpm-lock.yaml

# Reinstall
pnpm install

AI Gateway authentication fails

Problem: 401 Unauthorized when chatting.Solution:

Verify API key:
- Check .env.local has AI_GATEWAY_API_KEY
- Key should start with vg_
- No spaces or quotes around the value

Restart dev server:

# Stop server (Ctrl+C)
# Start again
pnpm dev

For Vercel deployments:
- Remove AI_GATEWAY_API_KEY (uses OIDC instead)
- Redeploy to apply changes

Port already in use

Problem: Error: listen EADDRINUSE: address already in use :::3000Solution:

# Option 1: Use different port
PORT=3001 pnpm dev

# Option 2: Kill process using port 3000
# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

TypeScript errors during build

Problem: Type errors prevent compilation.Solution:

# Check TypeScript version
pnpm list typescript
# Should be 5.6.3

# Clean build cache
rm -rf .next

# Rebuild
pnpm build

# If errors persist, check for type conflicts:
pnpm exec tsc --noEmit

Post-installation

Explore the database

Use Drizzle Studio to view your database visually:

pnpm db:studio

This opens a local web interface at https://local.drizzle.studio where you can:

Browse tables and data
Run queries
Edit records
View relationships

Run tests

Verify the installation with end-to-end tests:

pnpm test

This runs Playwright tests to ensure:

Pages load correctly
Authentication works
Chat functionality operates
Database operations succeed

Code quality checks

Run linting to catch code issues:

# Check for issues
pnpm lint

# Auto-fix formatting
pnpm format

Next steps

Quickstart guide

Follow the quickstart to get your chatbot running

Environment variables

Learn about all configuration options

Database setup

Deep dive into database configuration

Deploy to Vercel

Deploy your chatbot to production

Additional resources

Package Manager: pnpm documentation
Framework: Next.js 16 docs
AI SDK: Vercel AI SDK
Database: Drizzle ORM
Authentication: Auth.js documentation
UI Components: shadcn/ui

Having trouble? Join the Vercel Discord or open an issue on GitHub.

Get Started

Core Features

Deployment

Customization

System requirements

Required software

Cloud services

Installation steps

1. Clone the repository

2. Install dependencies

3. Configure environment variables

Detailed environment variable setup

4. Set up the database

Alternative: Manual database setup

5. Verify installation

Troubleshooting

Post-installation

Explore the database

Run tests

Code quality checks

Next steps

Quickstart guide

Environment variables

Database setup

Deploy to Vercel

Additional resources

Build docs developers (and LLMs) love

Get Started

Core Features

Deployment

Customization

​System requirements

​Required software

​Cloud services

​Installation steps

​1. Clone the repository

​2. Install dependencies

​3. Configure environment variables

​Detailed environment variable setup

​4. Set up the database

​Alternative: Manual database setup

​5. Verify installation

​Troubleshooting

​Post-installation

​Explore the database

​Run tests

​Code quality checks

​Next steps

Quickstart guide

Environment variables

Database setup

Deploy to Vercel

​Additional resources

Build docs developers (and LLMs) love

System requirements

Required software

Cloud services

Installation steps

1. Clone the repository

2. Install dependencies

3. Configure environment variables

Detailed environment variable setup

4. Set up the database

Alternative: Manual database setup

5. Verify installation

Troubleshooting

Post-installation

Explore the database

Run tests

Code quality checks

Next steps

Additional resources