Deployments

Deploy only when the stage justifies it. This guide covers branch strategy and Vercel setup for Catalyst projects.

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

Catalyst uses 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 for Catalyst. 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

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

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

Related docs