Deploying Next.js + Convex AI Apps to Vercel

Building an AI app is one thing — getting it running reliably in production is another. Deployment is where environment variables go missing, OAuth callbacks break, and your database silently points at the wrong instance. This guide walks through every step of deploying a Next.js + Convex AI app to Vercel, with enough detail that nothing falls through the cracks.

If you're still building your app, start with building your first AI agent in TypeScript and come back here when you're ready to ship.

Prerequisites

• Next.js 16 app with Convex
• Vercel account
• Convex account
• Claude API key from Anthropic
• A custom domain (optional)

What you'll build

You'll deploy a full AI app with:

• Next.js 16 frontend on Vercel
• Convex backend deployed to production
• Proper environment variables
• CI/CD with GitHub Actions
• Custom domain setup
• Monitoring and observability

1) Prepare your repo

Make sure your project builds locally before attempting a production deploy:

pnpm install
pnpm build

Fix any TypeScript errors or build warnings. A clean local build is the best predictor of a successful deploy.

Commit all changes to GitHub (using the amirbrooks account):

git add -A
git commit -m "chore: prepare for production deploy"
git push origin main

2) Set up Convex production

Your Convex development instance and production instance are separate. You need to explicitly deploy to production.

In your repo, run:

npx convex deploy

This creates a production deployment. Note the production URL, which looks like:

https://your-project.convex.cloud

Important: Your production Convex URL is different from your development URL. Double-check you're using the right one in your environment variables.

You can verify the deployment in the Convex dashboard:

1. Open your project in the Convex dashboard
2. Switch to the "Production" deployment
3. Check that your schema and functions are deployed
4. Test a query in the built-in console

3) Environment variable setup (detailed)

This is where most deployment failures happen. Here's every variable you need and where to find it:

Generate your AUTH_SECRET now if you haven't:

openssl rand -base64 32

For the auth setup details, see Convex Auth for AI Apps.

4) Configure Vercel project

In Vercel:

1. Click Add New → Project
2. Import your GitHub repo
3. Vercel auto-detects Next.js — confirm the framework preset
4. Configure build settings:
   • Build command: pnpm build
   • Output directory: .next
   • Install command: pnpm install
   • Root directory: . (unless you're in a monorepo)

Add environment variables in Vercel

Go to Settings → Environment Variables and add every variable from the table above.

Critical: Set variables for both Production and Preview environments. Preview deploys (from PRs) need their own Convex URL pointing to a development instance — don't let preview deploys hit your production database.

# Production environment
CONVEX_URL=https://your-project.convex.cloud
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY

# Preview environment (different Convex instance!)
CONVEX_URL=https://your-project-dev.convex.cloud
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY

For a deeper comparison of hosting options, see agent hosting and deploy options in 2026.

5) Deploy

Click Deploy in Vercel or push a commit to trigger a build.

Once deployed, test the live app and ensure:

• Auth callbacks return successfully
• Agent API routes respond
• Convex mutations work in production
• No console errors in the browser

# Quick smoke test from the command line
curl -s https://your-app.vercel.app/api/health | jq

6) Set up custom domain

In Vercel → Domains:

1. Add your domain (e.g., ai.amirbrooks.com.au)
2. Update DNS records at your registrar:

CNAME ai -> cname.vercel-dns.com

3. Wait for SSL to provision (usually under 5 minutes)
4. Verify by visiting https://ai.amirbrooks.com.au

If you're using a root domain (amirbrooks.com.au instead of a subdomain), you'll need an A record instead:

A @ 76.76.21.21

7) Configure OAuth callbacks for production

Update GitHub and Google OAuth apps to use the production domain:

https://ai.amirbrooks.com.au/api/auth/callback/github
https://ai.amirbrooks.com.au/api/auth/callback/google

Tip: Keep your localhost callback URLs too — you can add multiple redirect URIs. This way local development continues to work.

8) CI/CD with GitHub Actions

Automate deployments so every push to main deploys both Convex and Vercel:

Create .github/workflows/deploy.yml:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy-convex:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: npx convex deploy
        env:
          CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}

  deploy-vercel:
    runs-on: ubuntu-latest
    needs: deploy-convex
    steps:
      - uses: actions/checkout@v4
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

Add these secrets in GitHub → Settings → Secrets:

• CONVEX_DEPLOY_KEY — from Convex dashboard
• VERCEL_TOKEN — from Vercel account settings
• VERCEL_ORG_ID — from .vercel/project.json
• VERCEL_PROJECT_ID — from .vercel/project.json

The pipeline deploys Convex first (so schema changes are live before the frontend expects them), then triggers the Vercel build.

9) Verify Convex connection

Test a simple query from production to confirm the backend is connected:

import { ConvexHttpClient } from "convex/browser";
import { api } from "@/convex/_generated/api";

const client = new ConvexHttpClient(process.env.CONVEX_URL!);

export async function GET() {
  const health = await client.query(api.health.check, {});
  return Response.json({ ok: true, data: health });
}

10) Monitoring after deploy

A deployed app isn't a finished app. Set up monitoring from day one.

Vercel Analytics

Enable Vercel Analytics in your project settings. It gives you:

• Web Vitals (LCP, FID, CLS)
• Server function duration and errors
• Request volume and latency

Add the analytics component to your layout:

// app/layout.tsx
import { Analytics } from "@vercel/analytics/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  );
}

Convex Dashboard

The Convex dashboard shows:

• Function execution logs (queries, mutations, actions)
• Error rates and stack traces
• Database storage usage
• Real-time event stream

Check it daily for the first week after launch. Most issues surface within 48 hours.

11) Common deployment errors and fixes

12) Production checklist

Before calling your app "production-ready," verify everything on this list:

• All environment variables set in Vercel (Production + Preview)
• Convex deployed to production (npx convex deploy)
• OAuth callback URLs updated to production domain
• Custom domain configured and SSL provisioned
• AUTH_SECRET is unique per environment (don't share between dev and prod)
• Anthropic billing enabled (free tier has strict limits)
• Error pages configured (404, 500, auth errors)
• Rate limiting enabled on agent API routes
• Vercel Analytics enabled
• Convex dashboard bookmarked and checked
• GitHub Actions pipeline passing
• Preview deploys using separate Convex instance
• CORS headers configured if agents call from external origins

This is the same stack we recommend in our Next.js + Convex AI app stack guide.

13) Troubleshooting tips

• Build fails on Vercel: Ensure pnpm-lock.yaml is committed. Run pnpm install locally and push the lockfile.
• Auth callbacks fail: Update OAuth callback URLs to match the live domain exactly.
• Convex errors: Run npx convex deploy again if schema mismatches.
• Missing env vars: Confirm variables are set for the right environments (Production vs Preview vs Development).
• Cold start latency: First request after idle may be slow. This is normal for serverless — use Vercel's edge functions for latency-sensitive routes.

Final thoughts

Deployment is where AI apps break most often. With Vercel + Convex, you get fast iteration, reliable hosting, and scalable backends that are easy to maintain. The CI/CD pipeline ensures your Convex schema and Next.js frontend stay in sync, and the monitoring setup catches issues before your users do. Once the pipeline is stable, you can focus on building better agents. The AI Product Building course covers the full deployment workflow and beyond. If you want the full framework for going from idea to deployed AI product, the AI Product Building course covers the entire process.