Encore OS — Documentation

Version: 1.2.0
Last Updated: 2026-03-16

Overview

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

Project Configuration

Vercel Project Details

Property	Value
Team	`jeremy-blooms-projects-93ff6f2c`
Team ID	`team_qjGimov8j4mY2Ojqr7TpL5TI`
Project Name	`cloud-migration-path`
Project ID	`prj_iMHAljBMLDQXONzL9g7XUHH6CzrP`
Framework	Vite
Node Version	24.x
Production Domain	`northsightrecovery.app`
Staging Domain	`northsightrecovery.dev`

Deployment URLs

Environment	Branch	Domain
Production	`main`	`https://northsightrecovery.app`
Staging	`staging`	`https://northsightrecovery.dev`
Preview (branch)	feature branches	`https://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://anuwknikgsijbameytzr.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://anuwknikgsijbameytzr.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://anuwknikgsijbameytzr.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://anuwknikgsijbameytzr.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:

Variable	Purpose
`SENTRY_AUTH_TOKEN`	Sentry auth token (secret) for source map upload
`SENTRY_ORG`	Sentry organization slug (e.g. `encore-health-os`)
`SENTRY_PROJECT`	Sentry 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

Variable	Production	Preview	Development
VITE_SUPABASE_URL	✅	✅	✅
VITE_SUPABASE_ANON_KEY	✅	✅	✅
VITE_APP_ENV	✅	✅	✅
VITE_SENTRY_DSN	✅	✅	Optional
SENTRY_AUTH_TOKEN	Optional*	Optional*	—
SENTRY_ORG	Optional*	Optional*	—
SENTRY_PROJECT	Optional*	Optional*	—

*Optional for basic error capture; required for readable stack traces (source map upload).

Setting Environment Variables

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

Branch-to-Environment Mapping

Git Integration

Git Branch	Vercel Environment	Domain	Supabase Environment
`main`	Production	`northsightrecovery.app`	Production project
`staging`	Staging	`northsightrecovery.dev`	Staging branch
Feature branches	Preview	Auto-generated URL	Staging branch

Environment Configuration

Environment	VITE_APP_ENV	Supabase Branch
Production	`production`	Main project
Staging	`staging`	`staging` branch
Preview	`preview`	`staging` 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

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

Local Environment File

Create .env.local for local development:

VITE_SUPABASE_URL=https://anuwknikgsijbameytzr.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

Setting	Value	Purpose
`buildCommand`	`npm run build`	Production build command
`outputDirectory`	`dist`	Vite output directory
`installCommand`	`npm install --legacy-peer-deps`	Handle peer dependency conflicts
`framework`	`vite`	Framework detection
`rewrites`	SPA fallback	Client-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

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

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

Environment Variable Issues

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

Preview URL Not Working

Check deployment status in Vercel dashboard
Verify branch name is valid
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:

Domain	Target	Branch
`northsightrecovery.app`	Production	`main`
`northsightrecovery.dev`	Staging	`staging`

Configuring Custom Domains

Go to Project Settings → Domains
Add northsightrecovery.app
- Set as Production Domain
- Configure DNS records as instructed
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

Pre-Migration Test Plan (archived 2026-01 migration) - Comprehensive verification tests
Pre-Migration Checklist (archived 2026-01 migration) - Dashboard verification steps
Supabase Setup
Staging Setup Guide (archived 2026-01 migration)
Supabase MCP Usage
Sentry Verification Runbook - Confirm errors and source maps in Sentry after deploy

​Overview

​Project Configuration

​Vercel Project Details

​Deployment URLs

​Environment Variables

​Important: Same Supabase URL, Different Keys

​Required Variables

​Production

​Preview/Staging

​Development

​Sentry (error tracking and source maps)

​Environment Variable Scopes

​Setting Environment Variables

​Branch-to-Environment Mapping

​Git Integration

​Environment Configuration

​Preview Deployments

​Local Development

​Initial Setup

​Local Environment File

​vercel.json Configuration

​Key Settings

​Verification

​Using Verification Script

​Using Vercel MCP

​Verification Checklist

​Deployment

​Automatic Deployments

​Manual Deployments

​Troubleshooting

​Build Failures

​Environment Variable Issues

​Preview URL Not Working

​SPA Routing Issues

​Security Considerations

​Environment Variables

​Access Control

​Domain Configuration

​Custom Domains Setup

​Configuring Custom Domains

​DNS Configuration

​Related Documentation

Overview

Project Configuration

Vercel Project Details

Deployment URLs

Environment Variables

Important: Same Supabase URL, Different Keys

Required Variables

Production

Preview/Staging

Development

Sentry (error tracking and source maps)

Environment Variable Scopes

Setting Environment Variables

Branch-to-Environment Mapping

Git Integration

Environment Configuration

Preview Deployments

Local Development

Initial Setup

Local Environment File

vercel.json Configuration

Key Settings

Verification

Using Verification Script

Using Vercel MCP

Verification Checklist

Deployment

Automatic Deployments

Manual Deployments

Troubleshooting

Build Failures

Environment Variable Issues

Preview URL Not Working

SPA Routing Issues

Security Considerations

Environment Variables

Access Control

Domain Configuration

Custom Domains Setup

Configuring Custom Domains

DNS Configuration

Related Documentation