@vercel/edge-config

The Edge Config client SDK is the most ergonomic way to read data from Edge Configs. It provides several helper methods for reading values from one or multiple Edge Configs, and is compatible with Node.js, the Edge Runtime, and the browser.

It does not have functionality for creating new Edge Configs and writing to existing Edge Configs, which can be done using the Vercel REST API or the Dashboard.

You can also read Edge Config data with the Vercel REST API. Review Reading from an Edge Config to understand when to use the SDK versus the Vercel REST API.

Before you can start using the SDK, you need to have done the following:

• Created an Edge Config, which can be done using the API or the Dashboard
• Added an Edge Config read access token to access your Edge Config
• Defined a connection string with the Edge Config read access token and Edge Config id and stored it as an environment variable

To get started, install the SDK:

pnpm i @vercel/edge-config

Use connection strings to connect your Edge Config to one or more projects. This allows Vercel to optimize your reads when you read the Edge Config through the SDK. You can learn how to create a connection string here.

By default, the SDK will run all helper methods using the connection string stored in the EDGE_CONFIG environment variable. That means, if you have the EDGE_CONFIG environment variable set in your project, you can import any of the helper methods and use them like so:

import { NextResponse } from 'next/server';
import { getAll } from '@vercel/edge-config';
const configItems = await getAll();

However, you can store your connection string as any environment variable, and even connect to multiple Edge Configs by storing more than one connection string in your environment variables.

To do so, you must use the createClient helper.

The createClient helper method takes a connection string and returns an object that lets you use helper methods on the associated Edge Config. Using createClient, you can store multiple Edge Configs as environment variables and read data from all of them.

import { createClient } from '@vercel/edge-config';
// Fetch a single value from one config
const firstConfig = createClient(process.env.FIRST_EDGE_CONFIG);
const firstExampleValue1 = await firstConfig.get('other_example_key_1');
 
// Fetch all values from another config
const secondConfig = createClient(process.env.SECOND_EDGE_CONFIG);
const allValues = await secondConfig.getAll();

The following sections will teach you how to use all of the SDK's helper methods.

The get helper method allows you to fetch a value at a given key in your Edge Config. Create your API route using the get helper method in the pages/api or api directory of your project.

import { NextResponse } from 'next/server';
import { get } from '@vercel/edge-config';
 
export const runtime = 'edge';
 
export async function GET() {
  const exampleValue1 = await get('example_key_1');
  return NextResponse.json({
    label: `Value of "example_key_1" in my Edge Config.`,
    value: exampleValue1,
  });
}

The getAll helper method returns all of your Edge Config's items.

import { NextResponse } from 'next/server';
import { getAll } from '@vercel/edge-config';
 
export const runtime = 'edge';
 
export async function GET() {
  const configItems = await getAll();
  return NextResponse.json({
    label: `These are all the values in my Edge Config.`,
    value: configItems,
  });
}

Passing an array of key names causes getAll to return only the specified keys.

import { NextResponse } from 'next/server';
import { getAll } from '@vercel/edge-config';
 
export const runtime = 'edge';
 
export async function GET() {
  const someItems = await getAll(['keyA', 'keyB']);
  return NextResponse.json({
    label: `These are a few values in my Edge Config.`,
    value: someItems,
  });
}

The has helper method lets you verify if a key exists in your Edge Config. It returns true if the key does, and false if it doesn't.

import { NextResponse } from 'next/server';
import { has } from '@vercel/edge-config';
 
export const runtime = 'edge';
 
export async function GET() {
  const exampleKeyExists = await has('example_key_1');
  return NextResponse.json({
    keyExists: exampleKeyExists ? `The key exists!` : `The key doesn't exist!`,
  });
}

Every Edge Config has a hash string associated with it, which is updated whenever the Config is updated. Checking this digest can help you verify whether your Edge Config has properly updated, and confirm which version of the Config you're working with.

The digest helper method lets you check the version of the Edge Config you're reading.

import { NextResponse } from 'next/server';
import { digest } from '@vercel/edge-config';
 
export const runtime = 'edge';
 
export async function GET() {
  const version = await digest();
  return NextResponse.json({
    digest: version,
  });
}

You cannot write to Edge Config items using the Edge Config SDK. Instead, you can programmatically write using the Vercel REST API.

The Edge Config SDK is designed to read from our edge-config.vercel.com endpoint using read only tokens to authenticate reads, while writing requires Vercel Access Tokens to authenticate with the Vercel REST API. This core distinction makes it impractical to use the SDK for writes.

If your project requires frequent writes, you should learn more about Vercel KV.

All helper methods throw errors when:

• Your Edge Config read access token is invalid
• The Edge Config you're reading from doesn't exists
• A network error occurs