Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Version: 1.2.0
Last Updated: 2026-03-16

​
Overview

This guide documents the Vercel deployment configuration for the Encore Health OS Platform. The project uses Vercel for hosting the frontend application with environment-specific configurations.

​
Project Configuration

​
Vercel Project Details

PropertyValue
Teamjeremy-blooms-projects-93ff6f2c
Team IDteam_qjGimov8j4mY2Ojqr7TpL5TI
Project Namecloud-migration-path
Project IDprj_iMHAljBMLDQXONzL9g7XUHH6CzrP
FrameworkVite
Node Version24.x
Production Domainnorthsightrecovery.app
Staging Domainnorthsightrecovery.dev

​
Deployment URLs

EnvironmentBranchDomain
Productionmainhttps://northsightrecovery.app
Stagingstaginghttps://northsightrecovery.dev
Preview (branch)feature brancheshttps://cloud-migration-path-git-{branch}-jeremy-blooms-projects-93ff6f2c.vercel.app

​
Environment Variables

​
Important: Same Supabase URL, Different Keys

Note: The VITE_SUPABASE_URL being the same across all environments is CORRECT. We use Supabase Branching (not separate projects), which means:
  • Same base URL: https://zkgxozahyczcnzpwhbbf.supabase.co
  • Different anon keys per branch (critical for data isolation)
  • Data is isolated per branch; only migrations sync on merge
This is the expected configuration for Supabase branching. The anon key determines which branch’s data you access.

​
Required Variables

These environment variables must be configured in the Vercel dashboard for each environment:

​
Production

VITE_SUPABASE_URL=https://zkgxozahyczcnzpwhbbf.supabase.co
VITE_SUPABASE_ANON_KEY=<production-anon-key>
VITE_APP_ENV=production
VITE_SENTRY_DSN=<sentry-dsn-from-project-client-keys>

​
Preview/Staging

VITE_SUPABASE_URL=https://zkgxozahyczcnzpwhbbf.supabase.co
VITE_SUPABASE_ANON_KEY=<staging-anon-key>
VITE_APP_ENV=staging
VITE_SENTRY_DSN=<sentry-dsn-from-project-client-keys>

​
Development

VITE_SUPABASE_URL=https://zkgxozahyczcnzpwhbbf.supabase.co
VITE_SUPABASE_ANON_KEY=<development-anon-key>
VITE_APP_ENV=development
VITE_SENTRY_DSN=<optional-for-local-sentry-testing>

​
Sentry (error tracking and source maps)

For browser error capture and session replay, set VITE_SENTRY_DSN (from Sentry project → Settings → Client Keys). If unset, the client disables Sentry and no events are sent. For readable stack traces in production, set these build-time variables in Vercel so the Vite build uploads source maps:
VariablePurpose
SENTRY_AUTH_TOKENSentry auth token (secret) for source map upload
SENTRY_ORGSentry organization slug (e.g. encore-health-os)
SENTRY_PROJECTSentry project slug (e.g. sentry-rose-bucket)
When all three are set, vite.config.ts enables @sentry/vite-plugin and uploads source maps during npm run build. Omit for local builds if you do not need source map upload.

​
Environment Variable Scopes

VariableProductionPreviewDevelopment
VITE_SUPABASE_URL✅✅✅
VITE_SUPABASE_ANON_KEY✅✅✅
VITE_APP_ENV✅✅✅
VITE_SENTRY_DSN✅✅Optional
SENTRY_AUTH_TOKENOptional*Optional*—
SENTRY_ORGOptional*Optional*—
SENTRY_PROJECTOptional*Optional*—
*Optional for basic error capture; required for readable stack traces (source map upload).

​
Setting Environment Variables

  1. Go to Vercel Dashboard
  2. Select the cloud-migration-path project
  3. Navigate to Settings → Environment Variables
  4. Add each variable with the appropriate scope

​
Branch-to-Environment Mapping

​
Git Integration

Git BranchVercel EnvironmentDomainSupabase Environment
mainProductionnorthsightrecovery.appProduction project
stagingStagingnorthsightrecovery.devStaging branch
Feature branchesPreviewAuto-generated URLStaging branch

​
Environment Configuration

EnvironmentVITE_APP_ENVSupabase Branch
ProductionproductionMain project
Stagingstagingstaging branch
Previewpreviewstaging branch

​
Preview Deployments

Every pull request automatically receives a preview deployment with:
  • Unique URL based on branch name
  • Preview environment variables
  • Staging Supabase database connection

​
Local Development

​
Initial Setup

  1. Install Vercel CLI (optional): 
    npm i -g vercel
  2. Link Project (optional): 
    vercel link
  3. Pull Environment Variables (optional): 
    vercel env pull .env.local

​
Local Environment File

Create .env.local for local development: 
VITE_SUPABASE_URL=https://zkgxozahyczcnzpwhbbf.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
VITE_APP_ENV=development

​
vercel.json Configuration

The project uses vercel.json for build and deployment configuration: 
{
  "version": 2,
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "installCommand": "npm install --legacy-peer-deps",
  "framework": "vite",
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

​
Key Settings

SettingValuePurpose
buildCommandnpm run buildProduction build command
outputDirectorydistVite output directory
installCommandnpm install --legacy-peer-depsHandle peer dependency conflicts
frameworkviteFramework detection
rewritesSPA fallbackClient-side routing support

​
Verification

​
Using Verification Script

npm run verify:vercel

​
Using Vercel MCP

For AI-assisted verification, use these MCP commands: 
# List teams
mcp_vercel_list_teams

# List projects in team
mcp_vercel_list_projects --teamId team_qjGimov8j4mY2Ojqr7TpL5TI

# Get project details
mcp_vercel_get_project --projectId prj_iMHAljBMLDQXONzL9g7XUHH6CzrP --teamId team_qjGimov8j4mY2Ojqr7TpL5TI

# List deployments
mcp_vercel_list_deployments --projectId prj_iMHAljBMLDQXONzL9g7XUHH6CzrP --teamId team_qjGimov8j4mY2Ojqr7TpL5TI

​
Verification Checklist

  • vercel.json exists and is valid
  • Custom domains configured:
    • northsightrecovery.app → main branch (Production)
    • northsightrecovery.dev → staging branch (Staging)
  • DNS records configured for both domains
  • Environment variables set for all environments:
    • Production (main branch)
    • Staging (staging branch)
    • Preview (all other branches)
  • Sentry: VITE_SENTRY_DSN set for Production and Preview (enables browser error capture). Optionally SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT for source map upload during build.
  • Preview deployments working for feature branches
  • Supabase URLs point to correct projects/branches
  • Build succeeds without errors
  • SPA routing works correctly

​
Deployment

​
Automatic Deployments

Deployments are triggered automatically when:
  • Pushing to main branch (Production)
  • Pushing to any other branch (Preview)
  • Opening/updating pull requests

​
Manual Deployments

Using Vercel CLI: 
# Preview deployment
vercel

# Production deployment
vercel --prod
Using MCP: 
mcp_vercel_deploy_to_vercel

​
Troubleshooting

​
Build Failures

  1. Check build logs in Vercel dashboard
  2. Verify environment variables are set
  3. Run local build: npm run build
  4. Check for TypeScript errors: npm run typecheck

​
Environment Variable Issues

  1. Verify variable names match VITE_ prefix
  2. Check variable scopes (Production/Preview/Development)
  3. Redeploy after changing variables

​
Preview URL Not Working

  1. Check deployment status in Vercel dashboard
  2. Verify branch name is valid
  3. Wait for deployment to complete (check progress)

​
SPA Routing Issues

Ensure vercel.json has the rewrite rule: 
{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

​
Security Considerations

​
Environment Variables

  • ⚠️ Never commit .env.local or secrets to Git
  • ⚠️ Use scoped variables (don’t expose production keys in preview)
  • ⚠️ Rotate keys if accidentally exposed

​
Access Control

  • Only team members can access Vercel dashboard
  • Preview deployments may be publicly accessible
  • Consider enabling Vercel Authentication for staging

​
Domain Configuration

​
Custom Domains Setup

The following custom domains need to be configured in Vercel:
DomainTargetBranch
northsightrecovery.appProductionmain
northsightrecovery.devStagingstaging

​
Configuring Custom Domains

  1. Go to Project Settings → Domains
  2. Add northsightrecovery.app
    • Set as Production Domain
    • Configure DNS records as instructed
  3. Add northsightrecovery.dev
    • Assign to staging branch
    • Configure DNS records as instructed

​
DNS Configuration

For each domain, configure these DNS records at your registrar: A Record (Root Domain): 
@ → 76.76.21.21
CNAME (www subdomain - if needed): 
www → cname.vercel-dns.com