> ## 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.

# Vercel Integration Guide

> > Version: 1.2.0 > Last Updated: 2026-03-16

> **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

| 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://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

```env theme={null}
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

```env theme={null}
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

```env theme={null}
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:

| 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

1. Go to [Vercel Dashboard](https://vercel.com)
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 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

1. **Install Vercel CLI** (optional):
   ```bash theme={null}
   npm i -g vercel
   ```

2. **Link Project** (optional):
   ```bash theme={null}
   vercel link
   ```

3. **Pull Environment Variables** (optional):
   ```bash theme={null}
   vercel env pull .env.local
   ```

### Local Environment File

Create `.env.local` for local development:

```env theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
npm run verify:vercel
```

### Using Vercel MCP

For AI-assisted verification, use these MCP commands:

```bash theme={null}
# 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:

```bash theme={null}
# Preview deployment
vercel

# Production deployment
vercel --prod
```

Using MCP:

```bash theme={null}
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:

```json theme={null}
{
  "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

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
```

## Related Documentation

* [Pre-Migration Test Plan](../testing/PRE_MIGRATION_TEST_PLAN.md) - Comprehensive verification tests
* [Pre-Migration Checklist](../testing/PRE_MIGRATION_CHECKLIST.md) - Dashboard verification steps
* [Supabase Setup](./SUPABASE_SETUP.md)
* [Staging Setup Guide](../migration/STAGING_SETUP_GUIDE.md)
* [Supabase MCP Usage](../development/MCP_USAGE.md)
* [Sentry Verification Runbook](../development/SENTRY_VERIFICATION_RUNBOOK.md) - Confirm errors and source maps in Sentry after deploy