Global Config Lab

cd apps/experiments/global-config-lab
pnpm install
pnpm dev

The Global Config Lab reads key/value data from a Vercel Global Config store through the @vercel/global-config SDK. It is built for the kind of data you want to change without a redeploy and read on every request: feature flags, kill switches, and small runtime settings. The lab is read-only. You create and edit values in the Vercel dashboard (or API), then read them back here by key or as a full snapshot.

FeaturesCopy Anchor Link

• Read one key. Type a key (suggestions: greeting, maintenanceMode, featureCheckoutV2) and read its JSON value.
• Snapshot the store. Load every item with a single call and see the key count and JSON.
• Batch reads. POST accepts up to 20 keys and returns an entries map.
• Local fallback values. When the store is not configured, the 503 response includes demoDefaults so the UI still has something to show.
• Legacy-friendly detection. Either GLOBAL_CONFIG or the older EDGE_CONFIG variable marks the service as available.
• Read-only by design. The route never writes to the store.

API ReferenceCopy Anchor Link

Everything is served from one path. If neither GLOBAL_CONFIG nor EDGE_CONFIG is set, every method returns 503.

GET /api/global-configCopy Anchor Link

Reads a single key, or all items when no key is given.

POST /api/global-configCopy Anchor Link

Reads several keys in one request. The body is optional; invalid or empty JSON is treated as {}.

Implementation DetailsCopy Anchor Link

const status = getServiceStatus('global-config');
if (!status.available) {
  return NextResponse.json(
    {
      error: 'Global Config is not configured',
      setup:
        'Create a Global Config store in the Vercel dashboard (Storage - Global Config) and pull GLOBAL_CONFIG with `vercel env pull`.',
      demoDefaults: {
        maintenanceMode: false,
        greeting: 'hello from local fallback',
        featureCheckoutV2: true,
      },
    },
    { status: 503 },
  );
}

import { get, getAll } from '@vercel/global-config';

const key = new URL(request.url).searchParams.get('key');
if (key) {
  const value = await get(key);
  return NextResponse.json({ key, value, source: 'global-config' });
}

const all = await getAll();
return NextResponse.json({ items: all, source: 'global-config' });

const readSchema = z.object({
  keys: z.array(z.string().min(1).max(64)).max(20).optional(),
});

export function summarizeConfig(items: ConfigSnapshot | null | undefined) {
  if (!items || typeof items !== 'object') {
    return { keyCount: 0, keys: [] };
  }
  const keys = Object.keys(items).sort((a, b) => a.localeCompare(b));
  return { keyCount: keys.length, keys };
}

Use CasesCopy Anchor Link

• Kill switches. Flip maintenanceMode in the dashboard and read it in a Route Handler or proxy without redeploying.
• Feature flags. Gate behavior like featureCheckoutV2 by reading a boolean at request time.
• Runtime copy and settings. Banner text, redirect targets, allow-lists, and other small JSON values that change independently of code.
• A bridge to your own flag system. The Feature Flag Playground can read live definitions from Global Config, so the two labs pair well.

LimitationsCopy Anchor Link

• Read-only. This lab never writes. Create the store and edit keys in the Vercel dashboard or API.
• Slower locally. Production reads are optimized by the platform, but local development reads over the public internet, so latency is higher in pnpm dev.
• Small data. Global Config is intended for configuration, not for application data or large documents.
• Sequential batch reads. POST with keys calls get() once per key in a loop; the 20-key cap keeps this bounded.
• No auth on the demo route. Anyone who can reach the deployment can read every item in the connected store, so do not put secrets in it.
• Missing keys. get() returns undefined for unknown keys, which JSON serialization drops. The demo UI shows this as undefined.

Use in your projectCopy Anchor Link

Read a flag in a Route Handler. Install with pnpm add @vercel/global-config, then pull the connection string with vercel env pull.

// app/api/greeting/route.ts
import { get } from '@vercel/global-config';

export async function GET() {
  const [greeting, maintenanceMode] = await Promise.all([
    get<string>('greeting'),
    get<boolean>('maintenanceMode'),
  ]);

  if (maintenanceMode) {
    return Response.json({ error: 'Down for maintenance' }, { status: 503 });
  }

  return Response.json({ greeting });
}

DeploymentCopy Anchor Link

Deploy on Vercel

1. Create a Global Config store in the Vercel dashboard (Storage - Global Config) and connect it to your project. This provides GLOBAL_CONFIG.
2. Add the keys you want to read, for example greeting, maintenanceMode, and featureCheckoutV2.
3. Deploy with the platform button below, or redeploy your existing project so the variable is available.

Local DevelopmentCopy Anchor Link

pnpm install
pnpm dev

Link the project and pull the connection string:

vercel env pull .env.local
# or set it manually
echo 'GLOBAL_CONFIG=<connection-string>' >> .env.local

Try the API (default port 3000):

# Full snapshot
curl http://localhost:3000/api/global-config

# One key
curl "http://localhost:3000/api/global-config?key=greeting"

# Batch read
curl -X POST http://localhost:3000/api/global-config \
  -H "content-type: application/json" \
  -d '{"keys":["greeting","maintenanceMode","featureCheckoutV2"]}'

Expected response when the store is missing:

{
  "error": "Global Config is not configured",
  "setup": "Create a Global Config store in the Vercel dashboard (Storage - Global Config) and pull GLOBAL_CONFIG with `vercel env pull`.",
  "demoDefaults": {
    "maintenanceMode": false,
    "greeting": "hello from local fallback",
    "featureCheckoutV2": true
  }
}

ConfigurationCopy Anchor Link

From .env.example:

Limits in app/api/global-config/route.ts: at most 20 keys per POST, each 1–64 characters.

Vercel / Next.js Features UsedCopy Anchor Link

• Vercel Global Config (@vercel/global-config): get and getAll.
• Route Handlers with GET and POST exports and URLSearchParams query parsing.
• vercel env pull to sync the connection string for local development.
• Zod for batch-read validation.

Next StepsCopy Anchor Link