Deployment Guide

This guide covers deploying the 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 11.17.0 via Corepack (root packageManager pin)

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 build:vercel (production: Convex deploy + Next.js; Preview: Next.js only against shared prod Convex)

  • Framework: nextjs

If you need to override these in the Vercel dashboard:

  • Build Command: pnpm build:vercel

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

  • Install Command: pnpm install --frozen-lockfile

    If Vercel can’t see the monorepo lockfile from site-nextjs/, use: cd .. && pnpm install --frozen-lockfile (run the install from the workspace root).

Node.js Version

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

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

Reproducible Vercel settings (copy/paste)

Set these values so a fresh Vercel project reproduces the same monorepo build behavior:

  • Root Directory: site-nextjs

  • Build Command: pnpm build:vercel

  • Install Command: pnpm install --frozen-lockfile

  • If Vercel can’t see the workspace lockfile from site-nextjs/, use: cd .. && pnpm install --frozen-lockfile

  • Framework: nextjs

  • Output Directory: leave empty

  • Node.js Version: 24.x

  • Include source files outside of the Root Directory: enable (so Vercel can read root pnpm-workspace.yaml / pnpm-lock.yaml)

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: Production only (not Preview or Development while sharing prod data)

    • Name: NEXT_PUBLIC_CONVEX_URL

    • Value: The production https://<deployment>.convex.cloud URL

    • Environment: Preview and Development (and Production as a fallback)

CONVEX_DEPLOY_KEY on Preview would let branch builds push functions onto production Convex. Until release, Preview only reads/writes data via NEXT_PUBLIC_CONVEX_URL.

4. How Convex Deployment Works

When Vercel builds production:

  1. pnpm build:vercel sees VERCEL_ENV=production and runs pnpm convex deploy --cmd 'pnpm build'

  2. Convex deploys functions from convex/ using CONVEX_DEPLOY_KEY

  3. Next.js builds against that deployment

When Vercel builds Preview (or Development):

  1. pnpm build:vercel runs pnpm build only

  2. The app uses dashboard NEXT_PUBLIC_CONVEX_URL (same production data plane)

  3. Functions already on that Convex deployment are used; the Preview git branch does not convex deploy

Environment Variables

Required Environment Variables

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

  • CONVEX_DEPLOY_KEY — Production only

  • NEXT_PUBLIC_CONVEX_URL — Preview + Development (shared prod Convex until release)

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 the root pnpm-lock.yaml and pnpm-workspace.yaml. Local installs always run pnpm install from the repository root. See Tooling.

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 build:vercel

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

Best Practices

Shared data until release

Until apex launch, local next dev and Vercel Preview share production Convex data. Do not run npx convex dev against that URL. After release, split a staging/dev Convex and point Preview + local at it.

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

  • Dedicated website performance monitoring and website testing are on the product roadmap — no vendor research yet (see Monitoring & testing (roadmap)). A casual “e.g., Sentry” example is not a stack choice.

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.