Skip to content

Read Edge Configs with the SDK

Read data with low latency at the Edge

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 API or the Dashboard.

You can also read Edge Config data with the Vercel API. Review Using Edge Config to understand when to use the SDK versus the Vercel API.

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

To get started, install the SDK:


terminal
npm i @vercel/edge-config

Installing Vercel's Edge Config Client SDK using the npm command.

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 via 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:

example.ts
import { NextRequest, 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.

example.ts
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.

pages/api/example.ts
import { NextRequest, NextResponse } from 'next/server';
import { get } from '@vercel/edge-config';

export default (req: NextRequest) => {
  const exampleValue1 = await get('example_key_1');
  return NextResponse.json({
    example: `This is the value of "example_key_1" in my Edge Config: ${exampleValue1}!`,
  });
};

export const config = {
  runtime: 'experimental-edge',
};

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

pages/api/example.ts
import { NextRequest, NextResponse } from 'next/server';
import { getAll } from '@vercel/edge-config';

export default (req: NextRequest) => {
  const configItems = await getAll();
  return NextResponse.json({
    values: `These are all the values in my Edge Config: ${configItems}`,
  });
};

export const config = {
  runtime: 'experimental-edge',
};

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

pages/api/example.ts
import { NextRequest, NextResponse } from 'next/server';
import { getAll } from '@vercel/edge-config';

export default (req: NextRequest) => {
  const someItems = await getAll(['keyA', 'keyB']);
  return NextResponse.json({
    values: `These are a few values in my Edge Config: ${someItems}`,
  });
};

export const config = {
  runtime: 'experimental-edge',
};

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.

pages/api/example.ts
import { NextRequest, NextResponse } from 'next/server';
import { has } from '@vercel/edge-config';

export default (req: NextRequest) => {
  const exampleKeyExists = await has('example_key_1');
  return NextResponse.json({
    keyExists: exampleKeyExists ? `The key exists!` : `The key doesn't exist!`,
  });
};

export const config = {
  runtime: 'experimental-edge',
};

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.

pages/api/example.ts
import { NextRequest, NextResponse } from 'next/server';
import { digest } from '@vercel/edge-config';

export default (req: NextRequest) => {
  const version = await digest();
  return NextResponse.json({
    digest: version,
  });
};

export const config = {
  runtime: 'experimental-edge',
};

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