Deployment Guide

Uxie is designed to deploy seamlessly to Vercel with minimal configuration. This guide covers production deployment, environment setup, database migrations, and troubleshooting.

Deploying to Vercel

Quick Deploy

The fastest way to deploy Uxie:

Import Repository

Go to vercel.com and sign in
Click Add New → Project
Import your Git repository (GitHub, GitLab, or Bitbucket)

Configure Environment Variables

Add all required environment variables (see section below)

Deploy

Click Deploy and Vercel will:

Install dependencies
Run type checking
Build the application
Deploy to production

Vercel Configuration

Uxie uses default Vercel settings with Next.js 14. No vercel.json required. Build Settings:

Framework Preset: Next.js
Build Command: next build (default)
Output Directory: .next (default)
Install Command: pnpm install
Node Version: 18.x (recommended)

Override Package Manager

To use pnpm (recommended):

Go to Project Settings → General
Set Install Command to pnpm install
Vercel will auto-detect pnpm-lock.yaml

Automatic Deployments

Production

Triggered by pushes to main branch
Uses production environment variables
Deployed to uxie.vercel.app

Preview

Triggered by PRs and branch pushes
Uses preview environment variables
Unique URL per deployment
Great for testing before merge

Environment Variables

Required Production Variables

Add these in Vercel Dashboard → Settings → Environment Variables:

Database

DATABASE_URL="postgresql://user:password@host:port/database"

Important: Use your production Supabase database URL, not localhost.Enable connection pooling for serverless:

DATABASE_URL="postgresql://user:password@host:port/database?pgbouncer=true"

Authentication

NEXTAUTH_SECRET="<generate-with-openssl-rand>"
NEXTAUTH_URL="https://uxie.vercel.app"

GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-client-secret"

Important: Update Google OAuth redirect URIs to include:

https://uxie.vercel.app/api/auth/callback/google

File Upload

UPLOADTHING_TOKEN="your-production-token"

Create a separate UploadThing app for production to isolate uploads.

AI Services

# Pinecone (Vector Database)
PINECONE_API_KEY="your-api-key"
PINECONE_ENVIRONMENT="your-environment"

# HuggingFace (Embeddings)
HUGGINGFACE_API_KEY="hf_..."

# Google Gemini (LLM)
GOOGLE_GENERATIVE_AI_API_KEY="your-api-key"

Cost Considerations:

HuggingFace: Free tier sufficient for moderate usage
Pinecone: Free tier includes 1 index with 100k vectors
Google Gemini: Pay-per-token, 2.5 Flash is cost-effective

Optional Services

# Liveblocks (Collaboration - currently disabled)
NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_API_KEY="pk_..."

# Node Environment
NODE_ENV="production"

Environment Variable Security

Sensitive Keys

Never commit .env to git.Ensure .gitignore includes:

.env
.env.local
.env.*.local

Public Variables

Only NEXT_PUBLIC_* variables are exposed to browser.Keep API keys private unless intentionally public.

Managing Multiple Environments

Vercel supports three environments:

Environment	Branch	Use Case
Production	`main`	Live app for users
Preview	Any branch	Testing PRs
Development	Local	Local development

Set variables per environment in Vercel dashboard.

Database Migrations

Initial Production Setup

Create Production Database

Create new Supabase project for production
Note connection string
Enable connection pooling

Run Migrations Locally

Set production database URL temporarily:

export DATABASE_URL="postgresql://..."
pnpm prisma migrate deploy

Or push schema directly:

pnpm prisma db push

Verify Schema

Check schema with Prisma Studio:

pnpm prisma studio

Prisma Migration Commands

Development:

# Create migration and apply
pnpm prisma migrate dev --name add_summary_field

Production:

# Apply pending migrations
pnpm prisma migrate deploy

Schema Push (for prototyping):

# Push schema changes without migration files
pnpm prisma db push

Warning: db push can cause data loss. Use migrations in production.

Automated Migrations

Add migration script to package.json:

{
  "scripts": {
    "postinstall": "prisma generate",
    "build": "prisma generate && prisma migrate deploy && next build"
  }
}

Vercel runs these during build:

Generate Prisma Client
Apply pending migrations
Build Next.js app

Schema Changes Workflow

Develop Locally

Modify schema.prisma
Run pnpm prisma migrate dev --name description
Test locally

Commit Changes

Commit:

prisma/schema.prisma
prisma/migrations/ directory

git add prisma/
git commit -m "feat: add summary field to documents"

Deploy

Push to main branch.Vercel will:

Run migrations automatically
Build and deploy

Build Optimization

Environment-Specific Optimizations

next.config.mjs includes production optimizations:

const config = {
  reactStrictMode: true,
  swcMinify: true,  // Fast minification
  images: {
    domains: ["lh3.googleusercontent.com", "utfs.io"],
  },
};

Bundle Analysis

Analyze bundle size:

npm install -g @next/bundle-analyzer

Add to next.config.mjs:

const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer(config);

Run:

ANALYZE=true pnpm build

Edge Runtime Support

Some API routes use edge runtime for low latency:

export const runtime = 'edge';
export const maxDuration = 30;

Currently used in:

/api/chat - AI chat streaming
/api/completion - Text completion
/api/evaluate - Flashcard evaluation

Monitoring & Troubleshooting

Vercel Analytics

Enable in project settings:

Web Analytics - Page views, performance
Speed Insights - Core Web Vitals
Log Drains - Export logs to external services

Error Tracking

Build Errors

View in Vercel deployment logs:

TypeScript errors
Linting errors
Build failures

Runtime Errors

View in Vercel Functions logs:

API route errors
Server-side errors
Database connection issues

Common Production Issues

Database Connection Timeout

Problem: Serverless functions timeout connecting to database.Solution: Enable connection pooling in Supabase:

Get pooled connection string from Supabase dashboard
Update DATABASE_URL in Vercel
Redeploy

DATABASE_URL="postgresql://...?pgbouncer=true"

Environment Variable Not Found

Problem: Build fails with missing environment variable.Solution:

Check Vercel dashboard → Settings → Environment Variables
Ensure variable is set for correct environment (Production/Preview)
Redeploy

Verify with:

// src/env.mjs
import { createEnv } from "@t3-oss/env-nextjs";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    // ... all required variables
  },
});

Prisma Client Not Generated

Problem: Build fails with “Cannot find module ‘@prisma/client’”.Solution: Ensure postinstall script runs:

{
  "scripts": {
    "postinstall": "prisma generate"
  }
}

Vercel runs this automatically after pnpm install.

OAuth Redirect URI Mismatch

Problem: Google OAuth fails with redirect URI error.Solution: Update Google Cloud Console:

Go to console.cloud.google.com
APIs & Services → Credentials
Edit OAuth 2.0 Client

Add authorized redirect URI:

https://uxie.vercel.app/api/auth/callback/google

Save and wait 5 minutes for propagation

Rate Limiting Issues

Problem: AI features fail with 429 errors.Solution: Implement rate limiting:

Install Upstash Redis:

pnpm add @upstash/redis @upstash/ratelimit

Add to API routes:

import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, "1 h"),
});

Add Upstash environment variables to Vercel

Performance Monitoring

Monitor key metrics:

Core Web Vitals

LCP (Largest Contentful Paint): < 2.5s
FID (First Input Delay): < 100ms
CLS (Cumulative Layout Shift): < 0.1

API Response Times

Check Vercel Functions logs:

tRPC calls: < 500ms
AI chat: Streaming (1-3s)
Vector search: < 200ms

Database Performance

Monitor in Supabase dashboard:

Query performance
Connection pool usage
Slow queries

Rollback Strategy

Instant Rollback

Vercel keeps all deployments:

Go to Deployments tab
Find previous working deployment
Click ⋯ → Promote to Production
Instant rollback

Database Rollback

For schema changes:

# Revert last migration
pnpm prisma migrate resolve --rolled-back 20240306_migration_name

# Apply previous migration
pnpm prisma migrate deploy

Warning: Schema rollbacks can cause data loss. Always backup first.

CI/CD Integration

GitHub Actions Example

Automate checks before deploy:

name: CI
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'pnpm'
      
      - run: pnpm install
      - run: pnpm typecheck
      - run: pnpm lint
      - run: pnpm build

This runs on every PR before Vercel preview deployment.

Production Checklist

Before going live:

Custom Domain

Add your own domain:

Add Domain in Vercel

Go to Settings → Domains
Enter your domain (e.g., uxie.ai)
Click Add

Configure DNS

Add DNS records at your registrar:

Type: CNAME
Name: www (or @)
Value: cname.vercel-dns.com

Or use Vercel Nameservers for easier management.

Update Environment Variables

Update NEXTAUTH_URL to your domain:

NEXTAUTH_URL="https://yourdomain.com"

Update OAuth Redirects

Update Google OAuth redirect URIs to include your domain.

Scaling Considerations

Database

Supabase Limits:

Free: 500 MB, 2 GB bandwidth
Pro: 8 GB, 50 GB bandwidth

Consider upgrading as users grow.

Vector Database

Pinecone Limits:

Free: 1 index, 100k vectors
Standard: Multiple indexes, unlimited vectors

Monitor vector count per user.

File Storage

UploadThing Limits:

Free: 2 GB
Pro: 100 GB+

Implement file size limits per user.

AI API Costs

Google Gemini Pricing:

Input: $0.075 / 1M tokens
Output: $0.30 / 1M tokens

Implement rate limiting to control costs.

Next Steps

Architecture

Review system architecture for optimization opportunities

Contributing

Learn how to contribute improvements

Contributing

​Deployment Guide

​Deploying to Vercel

​Quick Deploy

​Vercel Configuration

​Automatic Deployments

Production

Preview

​Environment Variables

​Required Production Variables

​Environment Variable Security

Sensitive Keys

Public Variables

​Managing Multiple Environments

​Database Migrations

​Initial Production Setup

​Automated Migrations

​Schema Changes Workflow

​Build Optimization

​Environment-Specific Optimizations

​Bundle Analysis

​Edge Runtime Support

​Monitoring & Troubleshooting

​Vercel Analytics

​Error Tracking

Build Errors

Runtime Errors

​Common Production Issues

​Performance Monitoring

​Rollback Strategy

​Instant Rollback

​Database Rollback

​CI/CD Integration

​GitHub Actions Example

​Production Checklist

​Custom Domain

​Scaling Considerations

Database

Vector Database

File Storage

AI API Costs

​Next Steps

Architecture

Contributing

Build docs developers (and LLMs) love

Deployment Guide

Deploying to Vercel

Quick Deploy

Vercel Configuration

Automatic Deployments

Environment Variables

Required Production Variables

Environment Variable Security

Managing Multiple Environments

Database Migrations

Initial Production Setup

Automated Migrations

Schema Changes Workflow

Build Optimization

Environment-Specific Optimizations

Bundle Analysis

Edge Runtime Support

Monitoring & Troubleshooting

Vercel Analytics

Error Tracking

Common Production Issues

Performance Monitoring

Rollback Strategy

Instant Rollback

Database Rollback

CI/CD Integration

GitHub Actions Example

Production Checklist

Custom Domain

Scaling Considerations

Next Steps