Installation

Detailed setup instructions for the Vercel AI Chatbot

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 higher

Recommended: Node.js 20.x LTS or 22.x

The 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 pnpm@9.12.3

# 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.x

Required 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:

1. Go to github.com/vercel/openchat
2. Click Fork in the top right
3. 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:

.env.local

# 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:[e-mail]:5432/verceldb

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

Detailed environment variable setup

1. 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.

2. Set up AI Gateway

   1. Go to vercel.com/ai-gateway
   2. Click Create API Key
   3. Name it (e.g., “Chatbot Development”)
   4. Copy the key (starts with vg_)
   5. 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.

3. Create Postgres database

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

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

4. Set up Blob storage

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

   Redis improves performance with caching and rate limiting:

   1. In Vercel dashboard, go to Storage
   2. Click Create Database → Redis
   3. Copy the REDIS_URL
   4. 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 pnpm@9.12.3

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

Node version error

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

Solution:

# 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:

1. Check connection string:

   # Verify POSTGRES_URL is set
   echo $POSTGRES_URL
   
   # Test connection
   psql $POSTGRES_URL -c "SELECT version();"
   

2. Use Drizzle Studio to inspect:

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

3. 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:

1. Verify API key:

   • Check .env.local has AI_GATEWAY_API_KEY
   • Key should start with vg_
   • No spaces or quotes around the value

2. Restart dev server:

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

3. 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 :::3000

Solution:

# 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.