Deployment Guide

This guide covers deploying the Food Truck Nerdz Next.js application to Vercel with Convex backend integration.

Prerequisites

  • A GitHub account with the repository cloned

  • A Vercel account (sign up at vercel.com)

  • A Convex account (sign up at convex.dev)

  • Node.js 22+ installed locally

  • pnpm installed

Git Remote Configuration

Before deploying, ensure your git remotes are configured correctly:

Check Current Remotes

git remote -v

You should see: * origin pointing to your fork (e.g., https://github.com/YourUsername/ftn-site-vercel.git) * upstream pointing to the original repository (e.g., https://github.com/FoodTruckNerds/ftn-site-vercel.git)

Update Remotes (if needed)

# Set origin to your fork
git remote set-url origin https://github.com/YourUsername/ftn-site-vercel.git

# Set upstream to the original repository
git remote set-url upstream https://github.com/FoodTruckNerds/ftn-site-vercel.git

Vercel Project Setup

1. Create a New Vercel Project

  1. Go to Vercel Dashboard

  2. Click "Add New…​" → "Project"

  3. Import your GitHub repository

  4. Select the repository from the list

2. Configure Project Settings

In the project configuration screen, set the following:

Root Directory

Set the Root Directory to ftn-nextjs:

  1. In Vercel project settings, go to "Settings" → "General"

  2. Under "Root Directory", enter: ftn-nextjs

  3. This tells Vercel to treat the ftn-nextjs folder as the project root

Build & Output Settings

The project includes a vercel.json file in the ftn-nextjs directory that configures:

  • Build Command: npx convex deploy --cmd 'pnpm build'

  • Install Command: pnpm install

  • Framework: nextjs

If you need to override these in the Vercel dashboard:

  • Build Command: npx convex deploy --cmd 'pnpm build'

  • Output Directory: Leave empty (Vercel auto-detects .next for Next.js)

  • Install Command: pnpm install

Node.js Version

  1. In "Settings" → "General" → "Node.js Version"

  2. Set to 22.x (matches your package.json engines requirement)

Convex Deployment Setup

1. Create a Production Deployment

From your local machine, create a production Convex deployment:

cd ftn-nextjs
npx convex deploy

This will: * Create a production deployment in your Convex account * Deploy your Convex functions and schema * Provide a deployment URL

The --prod flag is not needed when using npx convex deploy --cmd in Vercel, as Convex automatically uses the production deployment in CI/CD environments.

2. Generate a Convex Deploy Key

  1. Go to your Convex Dashboard

  2. Navigate to your project settings

  3. Go to "Deploy Keys" or "Settings" → "Deploy Keys"

  4. Click "Generate Deploy Key"

  5. Copy the generated key (you’ll need this for Vercel)

3. Configure Convex in Vercel

  1. In Vercel, go to your project → "Settings" → "Environment Variables"

  2. Add the following environment variable:

    • Name: CONVEX_DEPLOY_KEY

    • Value: Paste the deploy key you generated from Convex

    • Environment: Select "Production" (and "Preview" if you want automatic deployments for preview branches)

The CONVEX_DEPLOY_KEY is required for Vercel to deploy your Convex functions during the build process.

4. How Convex Deployment Works

When Vercel builds your project:

  1. The build command npx convex deploy --cmd 'pnpm build' runs

  2. Convex deploys your functions from the convex/ directory

  3. Convex automatically sets NEXT_PUBLIC_CONVEX_URL during the build

  4. Your Next.js app builds with the correct Convex URL

  5. The frontend connects to your Convex backend automatically

You do not need to manually set NEXT_PUBLIC_CONVEX_URL in Vercel environment variables, as Convex sets it automatically during deployment. However, you can override it if needed.

Environment Variables

Required Environment Variables

Add these in Vercel → "Settings" → "Environment Variables":

  • CONVEX_DEPLOY_KEY - Your Convex deploy key (see above)

Optional Environment Variables

If you have other API keys or configuration, add them here:

  • Square API keys (if using Square integration)

  • Radar SDK keys (if using location services)

  • Any other service API keys your app requires

Set each variable for the appropriate environments: * Production: Used for production deployments * Preview: Used for preview deployments (pull requests, branches) * Development: Used for local development (if using Vercel CLI)

Deploying

First Deployment

  1. After configuring all settings, click "Deploy" in Vercel

  2. Vercel will:

    • Install dependencies with pnpm install

    • Deploy Convex functions

    • Build your Next.js application

    • Deploy to production

Subsequent Deployments

Vercel automatically deploys when you:

  • Push to the main/master branch (production)

  • Create a pull request (preview)

  • Push to other branches (preview, if configured)

Monitoring Deployments

  1. Check the "Deployments" tab in Vercel to see build logs

  2. If the build fails, check:

    • Build logs for errors

    • Environment variables are set correctly

    • CONVEX_DEPLOY_KEY is valid

    • Convex deployment completed successfully

Troubleshooting

Build Fails with "CONVEX_DEPLOY_KEY not found"

  • Ensure CONVEX_DEPLOY_KEY is set in Vercel environment variables

  • Verify it’s available for the environment you’re deploying to (Production/Preview)

  • Regenerate the key in Convex dashboard if needed

Build Fails with "NEXT_PUBLIC_CONVEX_URL is not set"

  • This usually means Convex deployment failed

  • Check that CONVEX_DEPLOY_KEY is correct

  • Verify your Convex project is properly configured

  • Check build logs for Convex-specific errors

Convex Functions Not Deploying

  • Ensure convex/ directory exists in ftn-nextjs/

  • Verify your vercel.json has the correct build command

  • Check that Convex CLI is available (it’s installed as a dependency)

Build Command Issues

If you see errors about the build command:

  • Verify vercel.json exists in ftn-nextjs/ directory

  • Check that the build command is: npx convex deploy --cmd 'pnpm build'

  • Ensure Root Directory is set to ftn-nextjs in Vercel settings

Best Practices

Separate Deployments

  • Use a separate Convex production deployment for Vercel (not your dev deployment)

  • Keep dev deployments for local development

  • This ensures production data is isolated

Environment-Specific Configuration

  • Use different Convex deployments for Production vs Preview if needed

  • Set environment-specific variables in Vercel

  • Test preview deployments before merging to main

Monitoring

  • Monitor Convex dashboard for function usage and errors

  • Check Vercel analytics for frontend performance

  • Set up error tracking (e.g., Sentry) for production issues

Next Steps

After successful deployment:

  • Test your production URL

  • Verify Convex functions are working

  • Check that all API integrations are functioning

  • Monitor for any errors or issues

For local development setup, see Getting Started.

For Convex-specific setup details, see Convex Setup.