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 24+ 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.git) * upstream pointing to the original repository (e.g., https://github.com/FoodTruckNerdz/ftn-site.git)

Update Remotes (if needed)

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

# Set upstream to the original repository
git remote set-url upstream {github-org-url}/{repo-ftn-site}.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 site-nextjs:

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

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

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

Build & Output Settings

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

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

  • Framework: nextjs

If you need to override these in the Vercel dashboard:

  • Build Command: pnpm 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 24.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 site-nextjs
pnpm 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 pnpm 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 pnpm 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)

Manual Deployment via CLI

If you need to force a deployment from your local machine (e.g., after changing the folder structure), you can use the Vercel CLI.

In a pnpm workspace, the directory context matters. Vercel needs to find the root pnpm-lock.yaml file.

1. Install Vercel CLI

pnpm add -g vercel

2. Link your project

Run this from the repository root (where pnpm-workspace.yaml is):

vercel link

Select your existing project from the list. This creates a .vercel folder at the root.

3. Force a Production Deployment

Run this also from the repository root:

vercel --prod

When running vercel --prod, the CLI may ask if you want to "Download Environment Variables for 'production'?".

Select NO (Reject this option).

Pulling environment variables from Vercel can overwrite your local configuration or create .env files that conflict with our project structure (which uses .env.vercel and .env.local for specific purposes). Always manage Vercel variables through the dashboard or manually in .env.vercel if needed for reference.

Vercel will use the Root Directory setting you configured in the dashboard (e.g., site-nextjs) to find the actual code, but running it from the repo root ensures all workspace dependencies are correctly uploaded.

Common Pitfalls

  • Broken Paths: If you run vercel --prod from inside the site-nextjs folder, the CLI might try to look for site-nextjs/site-nextjs because it applies the dashboard’s "Root Directory" setting relative to your current path. Always run from the repo root or use the --cwd . flag to override.

  • Node Version Mismatch: If you get a local warning about Node versions, ensure both your machine and Vercel are set to Node 24.

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 site-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 site-nextjs/ directory

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

  • Ensure Root Directory is set to site-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.