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

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 environment variable. That means, if you have the environment variable set in your project, you can import any of the helper methods and use them like so:

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 helper.

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

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

The helper method allows you to fetch a value at a given key in your Edge Config.

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

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

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

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 helper method lets you check the version of the Edge Config you're reading.

The digest's creation may change, so it is not documented. A matching digest indicates that the Edge Config content remains unchanged, while a different digest suggests changes but does not guarantee them.

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