Vercel Edge Config: Setup, SDK & Feature Flags Guide

Vercel Edge Config delivers configuration data to your edge functions in under 1ms — no database round-trip, no origin latency. This guide covers setup, the @vercel/edge-config SDK, feature flag patterns, and when to use Edge Config vs Vercel KV.

Setting Up Edge Config

# 1. Create Edge Config via Vercel CLI
vercel edge-config create my-feature-flags

# 2. Install SDK
npm install @vercel/edge-config

# 3. Add connection string to .env.local
# EDGE_CONFIG=https://edge-config.vercel.com/ecfg_xxxxx?token=xxxxx

# 4. Populate via Vercel API
curl -X PATCH \
  "https://api.vercel.com/v1/edge-config/${EDGE_CONFIG_ID}/items" \
  -H "Authorization: Bearer ${VERCEL_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "operation": "upsert", "key": "new-checkout", "value": { "enabled": true, "rollout": 50 } },
      { "operation": "upsert", "key": "dark-mode", "value": { "enabled": false } },
      { "operation": "upsert", "key": "maintenance", "value": false }
    ]
  }'

Reading Edge Config with the SDK

// middleware.ts — feature flag routing at edge
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { get, has } from '@vercel/edge-config';

export async function middleware(request: NextRequest) {
  // Check maintenance mode killswitch (~0.5ms)
  const inMaintenance = await get('maintenance');
  if (inMaintenance) {
    return NextResponse.rewrite(new URL('/maintenance', request.url));
  }

  // Feature flag: new checkout flow
  const checkoutFlag = await get<{ enabled: boolean; rollout: number }>('new-checkout');
  if (checkoutFlag?.enabled && request.nextUrl.pathname === '/checkout') {
    const userId = request.cookies.get('userId')?.value ?? '';
    // Simple hash-based rollout
    const hash = userId.split('').reduce((a, c) => a + c.charCodeAt(0), 0);
    if (hash % 100 < (checkoutFlag.rollout ?? 0)) {
      return NextResponse.rewrite(new URL('/checkout-v2', request.url));
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

A/B Testing Pattern with Edge Config

// A/B test assignment at the edge
import { get } from '@vercel/edge-config';
import { NextResponse } from 'next/server';

interface ABTest {
  variants: Array<{ id: string; weight: number; path: string }>;
}

export async function middleware(request: NextRequest) {
  const homeTest = await get<ABTest>('homepage-ab-test');

  if (!homeTest || request.nextUrl.pathname !== '/') {
    return NextResponse.next();
  }

  // Check if user already assigned
  const existing = request.cookies.get('ab-homepage');
  if (existing) {
    const variant = homeTest.variants.find(v => v.id === existing.value);
    if (variant) return NextResponse.rewrite(new URL(variant.path, request.url));
  }

  // Assign new variant
  const rand = Math.random();
  let cumWeight = 0;
  for (const variant of homeTest.variants) {
    cumWeight += variant.weight;
    if (rand < cumWeight) {
      const response = NextResponse.rewrite(new URL(variant.path, request.url));
      response.cookies.set('ab-homepage', variant.id, { maxAge: 86400 * 30 });
      return response;
    }
  }

  return NextResponse.next();
}

Storage Options Comparison