Vercel Proxy Setup

Vercel makes it easy to proxy Rybbit tracking through their Edge Network. If you're using Next.js, follow the Next.js proxy guide instead, which is optimized for Next.js applications.

This guide is for static sites or other frameworks deployed on Vercel.

Overview

Vercel supports rewrites in vercel.json, allowing you to proxy requests through their global Edge Network. This provides excellent performance with automatic caching at edge locations worldwide.

What you'll achieve:

• Proxy Rybbit through Vercel's Edge Network
• Automatic global caching and CDN distribution
• Simple JSON configuration
• Support all Rybbit features

Prerequisites

• Site deployed on Vercel
• Your Rybbit instance URL:
  • Cloud hosted: https://app.rybbit.io
  • Self-hosted: Your instance URL
• Your Rybbit site ID

Implementation

{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    },
    {
      "source": "/analytics/script-full.js",
      "destination": "https://app.rybbit.io/api/script-full.js"
    },
    {
      "source": "/analytics/replay.js",
      "destination": "https://app.rybbit.io/api/replay.js"
    },
    {
      "source": "/analytics/metrics.js",
      "destination": "https://app.rybbit.io/api/metrics.js"
    },
    {
      "source": "/analytics/track",
      "destination": "https://app.rybbit.io/api/track"
    },
    {
      "source": "/analytics/identify",
      "destination": "https://app.rybbit.io/api/identify"
    },
    {
      "source": "/analytics/session-replay/record/:siteId",
      "destination": "https://app.rybbit.io/api/session-replay/record/:siteId"
    },
    {
      "source": "/analytics/site/tracking-config/:siteId",
      "destination": "https://app.rybbit.io/site/tracking-config/:siteId"
    }
  ]
}

<script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>

git add vercel.json
git commit -m "Add Rybbit proxy configuration"
git push

How It Works

Vercel's Edge Network handles rewrites at the edge, close to your users:

1. Request hits Vercel's edge location nearest to the user
2. Edge server rewrites and proxies to Rybbit
3. Response is cached at the edge (for cacheable requests)
4. Subsequent requests serve from edge cache

This provides excellent performance with minimal configuration.

Performance Benefits

Edge Network Caching

Vercel automatically caches responses at edge locations:

• Scripts: Cached globally, served from nearest edge
• Configuration: Cached with appropriate TTL
• Tracking requests: Not cached (unique per request)

Global Distribution

Your analytics proxy benefits from Vercel's global CDN:

• 70+ edge locations worldwide
• Sub-100ms latency for most users
• Automatic failover and redundancy

Bandwidth Considerations

Troubleshooting

Rewrites not working

Problem: Requests still go to app.rybbit.io directly.

Solution:

1. Ensure vercel.json is in your project root
2. Redeploy after adding vercel.json
3. Clear browser cache and test in incognito mode

404 on tracking endpoints

Problem: Script loads but tracking returns 404.

Solution: Verify all endpoints are in vercel.json rewrites, including:

• /analytics/track
• /analytics/identify
• /analytics/session-replay/record/:siteId

Session replay not working

Problem: Basic tracking works but replay doesn't record.

Solution: Add replay endpoints to rewrites:

{
  "source": "/analytics/replay.js",
  "destination": "https://app.rybbit.io/api/replay.js"
},
{
  "source": "/analytics/session-replay/record/:siteId",
  "destination": "https://app.rybbit.io/api/session-replay/record/:siteId"
}

Environment-Specific Configuration

Using Environment Variables

While Vercel's vercel.json doesn't support environment variables directly, you can use different config files:

// vercel.json (production)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}

// vercel.staging.json (staging)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://staging.rybbit.io/api/script.js"
    }
  ]
}

Then specify config in build settings or use Vercel CLI:

vercel --prod --local-config vercel.json

Advanced Configuration

Headers

Add custom headers to responses:

{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ],
  "headers": [
    {
      "source": "/analytics/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=3600"
        }
      ]
    }
  ]
}

Redirects vs Rewrites

Don't use redirects for proxying (they're visible to the user):

// ❌ Wrong - uses redirects (user sees app.rybbit.io)
{
  "redirects": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}

// ✅ Correct - uses rewrites (transparent proxy)
{
  "rewrites": [
    {
      "source": "/analytics/script.js",
      "destination": "https://app.rybbit.io/api/script.js"
    }
  ]
}

Related Resources

• Next.js Proxy Guide - If using Next.js
• Tracking Script Documentation - Script configuration
• Vercel Rewrites Documentation - Official Vercel docs