Skip to main content

​
Overview

Lawn is designed to deploy seamlessly on Vercel with Convex as the backend. The deployment process automatically handles both the frontend build and Convex deployment in a single step.

​
Prerequisites

Before deploying, ensure you have:

​
Deployment Architecture

Lawn uses a coordinated deployment strategy:
  1. Convex deploys first - Backend functions and database schema
  2. Frontend builds - Vite builds the application with the Convex deployment URL
  3. Vercel serves - Static assets and server functions
This ensures the frontend always has the correct Convex endpoint URL.

​
Deploy to Vercel

1

Create a Convex production deployment

In your Convex dashboard:
  1. Navigate to your project at dashboard.convex.dev
  2. Go to Settings > Deployment Keys
  3. Click Generate Deploy Key
  4. Copy the deploy key (you’ll need it in the next step)
Keep your deploy key secure. It grants full access to deploy to your Convex project.
2

Import project to Vercel

  1. Go to vercel.com/new
  2. Import your Lawn repository from GitHub
  3. Select your repository and click Import
3

Configure build settings

Vercel should auto-detect the settings, but verify:
  • Framework Preset: Vite
  • Build Command: bun run build:vercel
  • Output Directory: dist
  • Install Command: bun install
The build:vercel script handles both Convex deployment and frontend build.
4

Add environment variables

In your Vercel project settings, go to Settings > Environment Variables and add:Required for deployment:
CONVEX_DEPLOY_KEY=prod:...
Frontend variables:
VITE_CONVEX_URL=https://your-production.convex.cloud
VITE_CONVEX_SITE_URL=https://your-production.convex.site
VITE_CLERK_PUBLISHABLE_KEY=pk_live_...
Use production keys (e.g., pk_live_, sk_live_) for your production deployment, not test keys.
5

Deploy

Click Deploy to start your first deployment.Vercel will:
  1. Install dependencies with bun install
  2. Run bun run build:vercel
  3. Deploy Convex functions
  4. Build the frontend with Vite
  5. Deploy to Vercel’s edge network

​
Understanding the Build Process

The build:vercel script in package.json runs: 
bunx convex deploy --cmd 'bun run build' --cmd-url-env-var-name VITE_CONVEX_URL
This command:
  1. Deploys your Convex functions to production
  2. Obtains the production Convex URL
  3. Sets VITE_CONVEX_URL to the production URL
  4. Runs bun run build (Vite build) with the correct URL
This ensures your frontend is built with the exact Convex deployment URL it will use in production.

​
Configure Convex Environment Variables

After your first deployment, configure environment variables in Convex:
1

Open Convex dashboard

Navigate to your production project at dashboard.convex.dev
2

Add production environment variables

Go to Settings > Environment Variables and add all backend secrets:
# Clerk
CLERK_SECRET_KEY=sk_live_...
CLERK_JWT_ISSUER_DOMAIN=your-domain.clerk.accounts.dev

# Mux
MUX_TOKEN_ID=...
MUX_TOKEN_SECRET=...
MUX_WEBHOOK_SECRET=...
MUX_SIGNING_KEY=...
MUX_PRIVATE_KEY=...

# Stripe
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_BASIC_MONTHLY=price_...
STRIPE_PRICE_PRO_MONTHLY=price_...
3

Redeploy

Push a new commit or manually redeploy in Vercel to apply the Convex environment variables.

​
Configure Webhooks

Update your webhook URLs in Mux and Stripe to point to your production Convex deployment.

​
Mux Webhooks

1

Open Mux dashboard

Go to mux.com
2

Update webhook URL

Navigate to Settings > Webhooks and update (or create) a webhook:
https://your-production.convex.site/mux/webhook
Ensure these events are enabled:
  • video.asset.ready
  • video.asset.errored
3

Verify webhook secret

Ensure the MUX_WEBHOOK_SECRET in Convex matches the signing secret shown in Mux.

​
Stripe Webhooks

1

Open Stripe dashboard

Go to stripe.com/dashboard
2

Update webhook URL

Navigate to Developers > Webhooks and add a new endpoint:
https://your-production.convex.site/stripe/webhook
Listen for these events:
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.payment_succeeded
  • invoice.payment_failed
3

Update webhook secret

Copy the signing secret and update STRIPE_WEBHOOK_SECRET in your Convex environment variables.

​
Domain Configuration

1

Add custom domain in Vercel

Go to Settings > Domains in your Vercel project and add your custom domain.
2

Update Clerk allowed origins

In your Clerk dashboard, go to Settings > Domains and add your production domain to the allowed origins.
3

Update CORS settings

Ensure your production domain is allowed in any CORS configurations for your APIs.

​
Continuous Deployment

Vercel automatically deploys when you push to your repository:
  • Production branch (usually main) - Deploys to production
  • Other branches - Creates preview deployments
Preview deployments can use the same Convex development environment, or you can create separate Convex projects for staging.

​
Production Checklist

Before going live, verify:
  • All environment variables are set with production keys
  • CONVEX_DEPLOY_KEY is configured in Vercel
  • Convex environment variables are configured in Convex dashboard
  • Mux webhook points to production Convex URL
  • Stripe webhook points to production Convex URL
  • Custom domain is configured and SSL is active
  • Clerk allows your production domain
  • Test user signup and authentication
  • Test video upload and processing
  • Test subscription creation and webhooks

​
Monitoring and Logs

​
Vercel Logs

View deployment and runtime logs:
  1. Go to your project in Vercel
  2. Click on a deployment
  3. View Build Logs or Function Logs

​
Convex Logs

View backend function logs:
  1. Go to dashboard.convex.dev
  2. Select your production project
  3. Click Logs in the sidebar
Convex logs include all console output from your backend functions, including errors and debugging information.

​
Troubleshooting

​
Build Failures

If the build fails:
  1. Check that CONVEX_DEPLOY_KEY is set correctly
  2. Verify Convex environment variables are configured
  3. Check Vercel build logs for specific errors
  4. Ensure all dependencies are in package.json

​
Webhook Failures

If webhooks aren’t working:
  1. Verify webhook URLs point to your production Convex site
  2. Check webhook secrets match in both service and Convex
  3. View webhook delivery logs in Mux/Stripe dashboards
  4. Check Convex logs for webhook handler errors

​
Authentication Issues

If users can’t sign in:
  1. Verify VITE_CLERK_PUBLISHABLE_KEY uses production key
  2. Ensure your domain is allowed in Clerk settings
  3. Check that CLERK_SECRET_KEY is set in Convex
  4. Verify JWT issuer domain matches

​
Video Processing Issues

If videos aren’t processing:
  1. Check Mux webhook is configured correctly
  2. Verify Mux credentials in Convex environment variables
  3. Check Convex logs for Mux API errors
  4. Ensure signing keys are configured for playback

​
Updating Production

To deploy updates:
  1. Push changes to your production branch
  2. Vercel automatically builds and deploys
  3. Convex deploys as part of the build process
  4. Monitor logs for any errors
Database schema changes in Convex require careful planning. Test migrations in a development environment first.

​
Rollback

If you need to rollback a deployment:
1

Rollback frontend

In Vercel, go to your project’s Deployments page and click Promote to Production on a previous deployment.
2

Rollback Convex (if needed)

Convex doesn’t have automatic rollback. You’ll need to:
  1. Revert your code changes
  2. Run bunx convex deploy manually
  3. Or push a commit that reverts the changes

​
Next Steps

Installation

Set up Lawn for local development

Environment Variables

Complete guide to all environment variables

Build docs developers (and LLMs) love

Get started for freeTalk to us