Deploy to Vercel

Step-by-step guide to deploying your AI chatbot to Vercel

Vercel is the recommended platform for deploying the AI Chatbot. This guide walks you through the complete deployment process.

Quick deploy

The fastest way to deploy is using the Deploy Button:

This will:

1. Fork the repository to your GitHub account
2. Create a new Vercel project
3. Configure basic settings
4. Deploy the application

After deployment, you’ll need to provision storage and configure environment variables.

Manual deployment

For more control over the deployment process, follow these steps:

1. Prerequisites

   Before deploying, ensure you have:

   • A Vercel account
   • A GitHub, GitLab, or Bitbucket account
   • The Vercel CLI installed: npm i -g vercel
   • Your repository pushed to your Git provider
2. Create Vercel project

   Option A: Using Vercel Dashboard

   1. Go to vercel.com/new
   2. Import your Git repository
   3. Configure project settings:
      • Framework Preset: Next.js
      • Build Command: tsx lib/db/migrate && next build (detected automatically)
      • Output Directory: .next (default)
      • Install Command: pnpm install (or your package manager)

   Option B: Using Vercel CLI

   vercel
   

   Follow the prompts to link your project and deploy.

3. Provision storage

   Add required storage services to your Vercel project:

   Postgres database

   1. Go to your project dashboard
   2. Click Storage tab
   3. Click Create Database
   4. Select Postgres
   5. Choose a region (select one close to your deployment region)
   6. Click Create

   Vercel automatically adds POSTGRES_URL and related variables to your project.

   Blob storage

   1. In the Storage tab
   2. Click Create Store
   3. Select Blob
   4. Click Create

   Vercel automatically adds BLOB_READ_WRITE_TOKEN to your project.

   Redis (KV)

   1. In the Storage tab
   2. Click Create Store
   3. Select KV (Redis)
   4. Click Create

   Vercel automatically adds REDIS_URL and related variables to your project.

4. Configure environment variables

   Set required environment variables in your Vercel project:

   1. Go to Settings → Environment Variables
   2. Add the following variables:

   AUTH_SECRET · string · required

   Generate a secret:

   openssl rand -base64 32
   

   Add this value to your environment variables.

   The following variables are automatically added when you provision storage:

   • POSTGRES_URL (Postgres)
   • BLOB_READ_WRITE_TOKEN (Blob)
   • REDIS_URL (KV)

   AI_GATEWAY_API_KEY is not required for Vercel deployments. AI Gateway uses OIDC tokens automatically.

5. Deploy

   Trigger a deployment:

   Option A: Push to Git

   git push origin main
   

   Vercel automatically deploys when you push to your main branch.

   Option B: Manual deployment via CLI

   vercel --prod
   

   Option C: Redeploy from dashboard

   1. Go to your project Deployments page
   2. Click the three dots menu on the latest deployment
   3. Click Redeploy
6. Verify deployment

   After deployment completes:

   1. Visit your deployment URL (e.g., your-project.vercel.app)
   2. Test the application:
      • Create an account or use guest mode
      • Start a chat conversation
      • Test file uploads
      • Create documents
   3. Check deployment logs for any errors

Configuration files

The application includes Vercel-specific configuration:

vercel.json

vercel.json

{
  "framework": "nextjs"
}

This tells Vercel to use Next.js framework detection.

next.config.ts

next.config.ts

import type { NextConfig } from "next";
import { withBotId } from "botid/next/config";

const nextConfig: NextConfig = {
  cacheComponents: true,
  images: {
    remotePatterns: [
      {
        hostname: "avatar.vercel.sh",
      },
      {
        protocol: "https",
        hostname: "*.public.blob.vercel-storage.com",
      },
    ],
  },
};

export default withBotId(nextConfig);

Key configuration:

• cacheComponents: true - Enables Next.js component caching
• images.remotePatterns - Allows images from:
  • avatar.vercel.sh (user avatars)
  • *.public.blob.vercel-storage.com (uploaded files)
• withBotId() - Wraps config with BotID security features

Environment-specific deployments

Vercel supports multiple environments:

Production

• Main branch deployments
• Production environment variables
• Production database
• URL: your-project.vercel.app

Preview

• Pull request and branch deployments
• Preview environment variables (optional)
• Can use separate preview database
• URL: your-project-git-branch.vercel.app

Development

• Local development with vercel dev
• Development environment variables
• Uses .env.local file
• URL: localhost:3000

Setting environment-specific variables

When adding environment variables in the Vercel dashboard, choose which environments they apply to:

• ✅ Production
• ✅ Preview
• ✅ Development

For sensitive production data, uncheck Preview to prevent preview deployments from accessing production resources.

AI Gateway configuration

The application uses Vercel AI Gateway to access multiple LLM providers through a unified interface.

Automatic authentication (Vercel deployments)

On Vercel, AI Gateway authentication is handled automatically using OIDC tokens. No additional configuration needed.

Supported models

The application is configured to use the following models through AI Gateway:

lib/ai/models.ts

export const DEFAULT_CHAT_MODEL = "openai/gpt-4.1-mini";

export const chatModels = [
  // Anthropic
  { id: "anthropic/claude-haiku-4.5", name: "Claude Haiku 4.5" },
  
  // OpenAI
  { id: "openai/gpt-4.1-mini", name: "GPT-4.1 Mini" },
  { id: "openai/gpt-5-mini", name: "GPT-5 Mini" },
  
  // Google
  { id: "google/gemini-2.5-flash-lite", name: "Gemini 2.5 Flash Lite" },
  { id: "google/gemini-3-pro-preview", name: "Gemini 3 Pro" },
  
  // xAI
  { id: "xai/grok-4.1-fast-non-reasoning", name: "Grok 4.1 Fast" },
  
  // Reasoning models
  { id: "anthropic/claude-3.7-sonnet-thinking", name: "Claude 3.7 Sonnet" },
  { id: "xai/grok-code-fast-1-thinking", name: "Grok Code Fast" },
];

How it works

The application uses the AI SDK’s Gateway provider:

lib/ai/providers.ts

import { gateway } from "@ai-sdk/gateway";

export function getLanguageModel(modelId: string) {
  return gateway.languageModel(modelId);
}

Vercel AI Gateway:

1. Routes requests to the appropriate LLM provider
2. Handles authentication automatically (OIDC on Vercel)
3. Provides unified API across all models
4. Includes rate limiting and monitoring

Documentation: https://vercel.com/docs/ai-gateway

Local development with Vercel

To develop locally with Vercel environment variables:

1. Install Vercel CLI

   npm i -g vercel
   
2. Link project

   vercel link
   

   Select your team and project. This creates a .vercel directory.

3. Pull environment variables

   vercel env pull
   

   This downloads environment variables to .env.local.

4. Run development server

   pnpm install
   pnpm db:migrate
   pnpm dev
   

   Your app runs on localhost:3000.

Alternatively, use vercel dev to run with Vercel’s development server:

vercel dev

This simulates the Vercel environment locally, including:

• Serverless functions
• Environment variables
• Edge functions
• Middleware

Monitoring and logs

Vercel provides built-in monitoring:

Deployment logs

1. Go to Deployments
2. Click on a deployment
3. View Build Logs and Function Logs

Runtime logs

1. Go to Logs tab
2. Filter by:
   • Time range
   • Status code
   • Source (Function, Edge, etc.)
   • Search query

Analytics

The application includes Vercel Analytics:

import { Analytics } from "@vercel/analytics/react";

View analytics in the Analytics tab:

• Page views
• Visitor stats
• Performance metrics
• Web Vitals

Custom domains

To add a custom domain:

1. Add domain

   1. Go to Settings → Domains
   2. Enter your domain name
   3. Click Add
2. Configure DNS

   Follow Vercel’s instructions to configure DNS:

   For apex domain (example.com):

   • Add A record to 76.76.21.21

   For subdomain (www.example.com):

   • Add CNAME record to cname.vercel-dns.com
3. Verify

   Vercel automatically verifies and provisions SSL certificates.

   Your app will be available at your custom domain within a few minutes.

Troubleshooting

Build fails - migration error

Cause: Database migration failed during build.

Solutions:

1. Check POSTGRES_URL is set correctly
2. Verify database is accessible from Vercel
3. Review build logs for specific error
4. Ensure database user has necessary permissions
5. For preview deployments, consider skipping migrations or using a preview database

Runtime error - Cannot find module

Cause: Missing dependency or build issue.

Solutions:

1. Check package.json includes all dependencies
2. Ensure build completed successfully
3. Try redeploying: vercel --prod --force
4. Check Node.js version compatibility

AI Gateway authentication failed

Cause: OIDC token issue or misconfiguration.

Solutions:

1. Verify project is deployed on Vercel (OIDC only works on Vercel)
2. Check AI Gateway is enabled for your account
3. Review function logs for detailed error messages
4. Ensure you’re not setting AI_GATEWAY_API_KEY (not needed on Vercel)

File upload fails

Cause: Blob storage not configured or token invalid.

Solutions:

1. Verify Blob store is provisioned
2. Check BLOB_READ_WRITE_TOKEN is set
3. Ensure token has read and write permissions
4. Review function logs for specific error

Session/auth issues

Cause: Missing or invalid AUTH_SECRET.

Solutions:

1. Verify AUTH_SECRET is set in environment variables
2. Generate a new secret: openssl rand -base64 32
3. Redeploy after adding the variable
4. Clear browser cookies and try again

Performance optimization

Edge runtime

Consider using Edge runtime for API routes that don’t need Node.js APIs:

export const runtime = 'edge';

Benefits:

• Faster cold starts
• Lower latency
• Better global distribution

Image optimization

Next.js automatically optimizes images on Vercel. Use the Image component:

import Image from 'next/image';

<Image src="..." width={200} height={200} alt="..." />

Caching

Configure caching in your API routes:

export const revalidate = 3600; // Cache for 1 hour

Security best practices

Follow these security practices for production deployments:

• Set AUTH_SECRET to a strong random value
• Use environment-specific databases (separate prod/preview/dev)
• Enable Vercel’s DDoS protection
• Configure allowed domains in CORS if needed
• Review security headers in next.config.ts
• Enable Vercel’s Web Application Firewall (WAF)
• Monitor logs for suspicious activity
• Keep dependencies updated

Next steps

Environment variables

Learn about all environment variables

Database setup

Configure and manage your database