# Vercel

> Vercel Deployment & Management

- Skill: `cooler09/vercel` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cooler09/vercel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cooler09/vercel/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cooler09 (https://skillmd.com/u/cooler09)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cooler09/vercel

---

# Vercel Deployment & Management

## Overview

This skill covers deploying and managing the Slay the Spire Deck Builder on Vercel's free Hobby tier. The project is split into two Vercel projects: **frontend** (React/Vite) and **backend** (Express as serverless functions).

## CLI Setup

```bash
# Install Vercel CLI globally
npm i -g vercel

# Login (opens browser)
vercel login

# Link a project (run from frontend/ or backend/ directory)
vercel link
```

## Available Tools

All tools are in `tools/vercel/`. Run from the copilot-skills root.

| Script | Purpose |
|--------|---------|
| `tools/vercel/deploy.sh` | Deploy frontend or backend to Vercel |
| `tools/vercel/status.sh` | List recent deployments |
| `tools/vercel/env.sh` | Manage environment variables |
| `tools/vercel/logs.sh` | View deployment and function logs |

### Deploy

```bash
# Preview deploy (default)
./tools/vercel/deploy.sh --project frontend

# Production deploy
./tools/vercel/deploy.sh --project backend --prod

# With explicit token (CI environments)
./tools/vercel/deploy.sh --project frontend --prod --token $VERCEL_TOKEN
```

### Environment Variables

```bash
# List all env vars
./tools/vercel/env.sh list --project frontend

# Add a variable to production
./tools/vercel/env.sh add VITE_SUPABASE_URL https://xyz.supabase.co --project frontend --env production

# Pull remote env vars to local .env.local
./tools/vercel/env.sh pull --project frontend

# Remove a variable
./tools/vercel/env.sh remove OLD_VAR --project backend --env production
```

### Deployment Status & Logs

```bash
# Recent deployments
./tools/vercel/status.sh --project frontend --limit 10

# View logs (one-shot)
./tools/vercel/logs.sh --project backend

# Stream logs in real-time
./tools/vercel/logs.sh --project backend --follow
```

## Project Configuration

### Frontend (`frontend/vercel.json`)

```json
{
  "buildCommand": "npm install && npm run build",
  "devCommand": "npm run dev",
  "installCommand": "npm install"
}
```

- **Root directory**: `./frontend`
- **Framework**: Vite
- **Output**: `dist/`

### Backend (`backend/vercel.json`)

```json
{
  "version": 2,
  "builds": [{ "src": "api/index.js", "use": "@vercel/node" }],
  "routes": [{ "src": "/api/(.*)", "dest": "api/index.js" }]
}
```

- **Root directory**: `./backend`
- **Runtime**: `@vercel/node` (serverless)
- Express app is exported as `default` from `api/index.js`

## Required Environment Variables

### Frontend (Vercel Dashboard)

| Variable | Description | Example |
|----------|-------------|---------|
| `VITE_SUPABASE_URL` | Supabase project URL | `https://xyz.supabase.co` |
| `VITE_SUPABASE_ANON_KEY` | Supabase public/anon key | `eyJ...` |
| `VITE_API_URL` | Backend API URL | `https://api-xyz.vercel.app` |
| `VITE_ENV` | Environment mode | `production` |

### Backend (Vercel Dashboard)

| Variable | Description | Example |
|----------|-------------|---------|
| `SUPABASE_URL` | Supabase project URL | `https://xyz.supabase.co` |
| `SUPABASE_ANON_KEY` | Supabase public/anon key | `eyJ...` |
| `SUPABASE_SERVICE_ROLE_KEY` | Supabase secret key | `eyJ...` |
| `NODE_ENV` | Must be `production` | `production` |
| `FRONTEND_URL` | Frontend URL for CORS | `https://my-app.vercel.app` |

## GitHub Actions Integration

The CI/CD pipeline in `.github/workflows/ci-cd.yml` deploys to Vercel on push to `main`. Required GitHub secrets:

| Secret | Where to find it |
|--------|-----------------|
| `VERCEL_TOKEN` | vercel.com → Settings → Tokens |
| `VERCEL_ORG_ID` | vercel.com → Settings → General |
| `VERCEL_PROJECT_ID` | Vercel project → Settings → General |

## Common Tasks

### Debugging a Failed Deploy

1. Check logs: `./tools/vercel/logs.sh --project backend`
2. Verify env vars: `./tools/vercel/env.sh list --project backend`
3. Check Vercel dashboard build logs for the specific error
4. Test locally: `npm run build --workspace=backend`

### Rolling Back

```bash
# In the Vercel dashboard: Deployments → click a previous deploy → "Promote to Production"
# Or via CLI:
vercel rollback
```

### Custom Domain

```bash
vercel domains add yourdomain.com
vercel domains verify yourdomain.com
```

## Free Tier Limits

- **Bandwidth**: 100 GB/month
- **Serverless function executions**: 1M/month
- **Build minutes**: included (with queue)
- **Deployments**: unlimited
- **Projects**: unlimited on Hobby