Vercel Skill

Use this skill when deploying Adynato projects to Vercel or troubleshooting deployment issues.

Common Errors

VERCEL_ORG_ID and VERCEL_PROJECT_ID

Error: You specified `VERCEL_ORG_ID` but you forgot to specify `VERCEL_PROJECT_ID`.
You need to specify both to deploy to a custom project.

Fix: Both environment variables must be set together:

# Get these from Vercel dashboard or .vercel/project.json
export VERCEL_ORG_ID="team_xxxxxx"
export VERCEL_PROJECT_ID="prj_xxxxxx"

Or in CI (GitHub Actions):

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
  VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

Finding your IDs:

# After linking a project, check .vercel/project.json
cat .vercel/project.json
# {"orgId":"team_xxx","projectId":"prj_xxx"}

Project Not Linked

Error: Your codebase isn't linked to a project on Vercel.

Fix:

# Interactive linking
vercel link

# Or with flags for CI
vercel link --yes --project=my-project --scope=my-team

Build Command Failed

Error: Command "npm run build" exited with 1

Debug steps:

1. Check build logs in Vercel dashboard
2. Run build locally: npm run build
3. Check for missing environment variables
4. Verify Node.js version matches (engines in package.json)

Environment Variable Not Found

Error: Environment variable "DATABASE_URL" not found

Fix: Add to Vercel dashboard or via CLI:

# Add single variable
vercel env add DATABASE_URL production

# Pull all env vars locally
vercel env pull .env.local

Project Configuration

vercel.json

{
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "installCommand": "npm install",
  "framework": "nextjs",
  "regions": ["iad1"],
  "functions": {
    "app/api/**/*.ts": {
      "memory": 1024,
      "maxDuration": 30
    }
  },
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" }
      ]
    }
  ],
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page",
      "permanent": true
    }
  ],
  "rewrites": [
    {
      "source": "/blog/:slug",
      "destination": "/posts/:slug"
    }
  ]
}

Framework Presets

Vercel auto-detects, but you can override:

Framework	framework value	Output Directory
Next.js	nextjs	.next
Remix	remix	build
Astro	astro	dist
Vite	vite	dist
Create React App	create-react-app	build

Environment Variables

Scopes

Scope	When Used
production	Production deployments (main branch)
preview	Preview deployments (PRs, other branches)
development	Local development (vercel dev)

Managing Env Vars

# Add variable to all environments
vercel env add SECRET_KEY

# Add to specific environment
vercel env add SECRET_KEY production

# List all variables
vercel env ls

# Remove variable
vercel env rm SECRET_KEY production

# Pull to local .env file
vercel env pull .env.local

Sensitive vs Plain

• Sensitive: Encrypted, not visible in dashboard after creation
• Plain: Visible, editable in dashboard

# Add as sensitive (default for secrets)
vercel env add DATABASE_URL --sensitive

CLI Commands

Deployment

# Deploy to preview
vercel

# Deploy to production
vercel --prod

# Deploy without prompts (CI)
vercel --yes --prod

# Deploy with specific env
vercel --env NODE_ENV=production

Project Management

# Link to existing project
vercel link

# List projects
vercel projects ls

# Remove project
vercel projects rm my-project

# List deployments
vercel ls

# Inspect deployment
vercel inspect <deployment-url>

# View logs
vercel logs <deployment-url>

# Rollback
vercel rollback <deployment-url>

Domains

# Add domain
vercel domains add example.com

# List domains
vercel domains ls

# Remove domain
vercel domains rm example.com

# Add domain to project
vercel alias <deployment-url> example.com

CI/CD with GitHub Actions

Basic Deployment

# .github/workflows/deploy.yml
name: Deploy to Vercel

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Vercel CLI
        run: npm install -g vercel

      - name: Pull Vercel Environment
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

      - name: Build
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

Preview on PR

- name: Deploy Preview
  if: github.event_name == 'pull_request'
  run: |
    url=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})
    echo "Preview URL: $url"

Monorepo Setup

Root vercel.json for Monorepo

{
  "projects": [
    { "src": "apps/web", "use": "@vercel/next" },
    { "src": "apps/api", "use": "@vercel/node" }
  ]
}

Deploying Specific App

# Set root directory in project settings or:
vercel --cwd apps/web

Turborepo Integration

# vercel.json at root
{
  "buildCommand": "cd ../.. && npx turbo run build --filter=web",
  "installCommand": "cd ../.. && npm install"
}

Troubleshooting

Check Deployment Status

# List recent deployments
vercel ls

# Get deployment details
vercel inspect <url>

# Stream logs
vercel logs <url> --follow

Function Timeouts

Default is 10s for Hobby, 60s for Pro. Increase in vercel.json:

{
  "functions": {
    "app/api/slow-endpoint/route.ts": {
      "maxDuration": 60
    }
  }
}

Memory Issues

{
  "functions": {
    "app/api/heavy-compute/route.ts": {
      "memory": 3008
    }
  }
}

Build Cache Issues

# Force rebuild without cache
vercel --force

Or in dashboard: Deployments → Redeploy → "Redeploy with existing Build Cache" unchecked.