Deployments

GuideReference

Branch strategy and Vercel deployment for Catalyst projects.

Read this when you're ready to deploy beyond local development.
Deploy only when the stage justifies it — POC stays local, MVP+ goes live.

Deploy at the right time

  • POC: Keep local or use password-protected previews. No public traffic.
  • MVP/MMP: Deploy to preview/UAT environments for testing with real users.
  • PROD: Requires Refine checkpoint approval, monitoring, and rollback plan.

Branch Strategy

A simple branch strategy that maps to deployment environments.

main / masterRequired

Production

Stable, release-ready code. Deploys to production domain.

developOptional

UAT / Staging

Integration branch. Deploys to preview URL for UAT testing.

demoOptional

Demo

Demo-specific branch. Deploys to demo subdomain for stakeholders.

Typical flow

Feature branches → develop (UAT) → main (Production)

Vercel Setup

Vercel is the recommended deployment platform. It provides automatic deployments, preview URLs, and environment management.

1

Connect your repository

  1. Go to vercel.com/new and import your GitHub/GitLab/Bitbucket repository.
  2. Vercel auto-detects Next.js — accept the default build settings.
  3. Click Deploy to create your first production deployment.
2

Configure production branch

  1. Go to Project Settings → Git.
  2. Set Production Branch to main (or master).
  3. Pushes to this branch deploy to your production domain.
3

Set up preview branches (optional)

Every branch automatically gets a preview URL. For stable environments like UAT or demo:

  1. Go to Project Settings → Domains.
  2. Add a subdomain like uat.yourproject.com.
  3. Under Git Branch, select develop.
  4. Repeat for demo branch if needed.
4

Configure environment variables

  1. Go to Project Settings → Environment Variables.
  2. Add your variables (e.g., Supabase keys, API URLs).
  3. Select which environments each variable applies to:
    • Production — Main/master branch
    • Preview — All other branches (develop, demo, feature branches)
    • Development — Local development (use vercel env pull)

Tip: Branch-specific variables

For different values on develop vs. demo, add the variable twice with Preview environment and specify the branch for each.

5

Sync environment variables locally

Pull environment variables from Vercel to your local .env file:

# Install Vercel CLI
pnpm i -g vercel

# Link to your project (first time only)
vercel link

# Pull development environment variables
vercel env pull

This creates a .env file with your Development environment variables.

Environment Configuration

Understanding client-side vs server-side variables.

Client-side variables

Prefix with NEXT_PUBLIC_. Safe for public use, bundled in client JavaScript.

NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_APP_ENV=production

Server-side variables

No prefix. Only available in server components and API routes. Safe for secrets.

SUPABASE_SERVICE_ROLE_KEY=...
AUTH_SECRET=...

Always update .env.example

When adding new environment variables, update .env.example with the variable name (not the value) so other developers know what's required.

Production Deployment Checklist

Verify these items before deploying to production.

  • All environment variables configured for Production
  • Custom domain configured and DNS propagated
  • SSL certificate active (automatic with Vercel)
  • Analytics/monitoring integrated
  • Error tracking configured (e.g., Sentry)
  • Build succeeds without warnings
  • Refine checkpoint passed — see Delivery cycles

Next Steps

Where to go from here:

Upgrade Checklists

Technical work for stage transitions.

Deploy & Observe Audit

Deployment quality verification.

Delivery Cycles

How the delivery loop works at each stage.

Vercel Documentation

↗

Official Vercel docs for advanced configuration.