Skip to main content

Vercel + Upstash Setup Guide

Quick Setup (Recommended) ⚡​

Since you're deploying to Vercel, the easiest way to set up Redis caching is through the Vercel Marketplace integration.

Step-by-Step:​

  1. Go to your Vercel Dashboard

    • Navigate to your project
    • Click on "Integrations" tab
    • Click "Browse Marketplace"

  2. Install Upstash

  3. Connect Upstash Account

    • Sign in or create a free Upstash account
    • Authorize Vercel to access Upstash

  4. Create/Select Database

    • Choose "Global" for best performance (recommended)
    • Or select an existing database
    • Click "Link"

  5. Done! ✅

    • Vercel automatically sets REDIS_URL environment variable
    • Your app is ready to use Redis caching
    • No manual configuration needed!

What Gets Set Up Automatically​

The Vercel integration automatically:

  • ✅ Creates/links Upstash Redis database
  • ✅ Sets REDIS_URL environment variable
  • ✅ Configures for all environments (Development, Preview, Production)
  • ✅ Handles authentication and connection strings

Verify Setup​

After installation, check your environment variables:

  1. Go to Project Settings → Environment Variables
  2. You should see REDIS_URL automatically added
  3. The value will be something like: rediss://default:password@host:6379

Enable Redis in Your App​

Make sure your .env.local (for local development) includes:

ENABLE_REDIS=true

Note: REDIS_URL is automatically set by Vercel in production/preview environments. For local development, you can either:

  • Copy the REDIS_URL from Vercel to your .env.local
  • Or use the in-memory cache fallback (works fine for local dev)

Testing​

  1. Deploy to Vercel (or run locally with REDIS_URL set)

  2. Check logs for cache messages:

    • ✅ Cache hit for locale: en - Cache working!
    • ⏳ Cache miss for locale: en - Fetching from Sanity (first time)

  3. Test cache invalidation:

    curl -X POST https://your-domain.com/api/cache/clear?all=true \
      -H "Authorization: Bearer your-secret-token"

Benefits of Vercel Marketplace Integration​

✅ One-click setup - No manual configuration
✅ Automatic env vars - Vercel handles everything
✅ Multi-environment - Works in dev, preview, and production
✅ Easy management - Manage from Vercel dashboard
✅ Free tier - Upstash free tier included
✅ Global edge - Fast worldwide performance

Troubleshooting​

Redis not connecting?​

  1. Check environment variables:

    • Go to Vercel → Project Settings → Environment Variables
    • Verify REDIS_URL is set
    • Check it's enabled for the right environments

  2. Check logs:

    • Look for [Cache] Redis connected in logs
    • If you see [Cache] Redis not available, check the connection string

  3. Verify Upstash database:

Local development issues?​

For local development, you have two options:

Option 1: Use Upstash locally

# .env.local
ENABLE_REDIS=true
REDIS_URL=rediss://default:password@your-upstash-endpoint:6379

Option 2: Use in-memory cache (simpler)

# .env.local
ENABLE_REDIS=false
# Or just don't set ENABLE_REDIS

The app automatically falls back to in-memory cache if Redis is unavailable.

Next Steps​

  1. ✅ Install Upstash from Vercel Marketplace
  2. ✅ Deploy your app
  3. ✅ Monitor cache performance in logs
  4. ✅ Set up Sanity webhook for automatic cache invalidation (see Caching Overview and Sanity Webhooks)

Resources​