Skip to content

Edge Config Get Started Guide

Get started with reading data at fast speeds with a few steps. Set up your Edge Config for any use case

You can get started with reading data from Edge Config within minutes by using the creation workflow in the Edge Config section of your Project.

Follow the Quickstart to do so.

You can also create and configure your Edge Config at the account level for all use cases by:

In this section, you will create an Edge Config called hello_world_store in your Project. A token called web-app-token, key-value data pair greeting: "hello world" and environment variable EDGE_CONFIG will be automatically created for you. You will then read the value of greeting from a local Next.js project.

Edge Config Section for a Project

  • Navigate to your Project page and click on the Edge Config tab
  • Click Create Project Store and type hello_world_store for your Edge Config name in the dialog that opens and click Create
Note: The name can only contain alphanumeric letters, "_" and "-". It cannot exceed 32 characters.
  • Once created, you will see a summary of what was created for you. Click Show Edge Config
  • Then, follow the steps in the section Learn how to use this in code which assumes your project uses Next.js. These steps are outlined next
  • On your local machine, connect your Vercel Project
  • Pull your latest environment variables, specifically EDGE_CONFIG so that it's available to your project locally
terminal
vc pull
  • Install the Edge Config SDK

terminal
npm i @vercel/edge-config

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

  • Paste the following code in middleware.js at the root of the project
middleware.js
import { NextResponse } from 'next/server';
import { get } from '@vercel/edge-config';

export const config = { matcher: '/welcome' };

export async function middleware() {
  const greeting = await get('greeting');
  return NextResponse.json(greeting);
}
  • Run your application locally and visit localhost:3000/welcome to see your greeting. The middleware intercepts requests to localhost:3000/welcome and responds with a greeting read from your Edge Config

Your project is now ready to read more key-value data pairs from the hello_world_store Edge Config using the SDK or the Vercel API.

Note: Your Edge Config uses the public internet for reads when you develop locally. Therefore, you will see higher response times. However, when you deploy your application to Vercel, the reads are optimized to happen at ultra low latency without any network requests.

In the section that follows, you will learn how to generate a token and connection string manually at your account level using the Dashboard and the Vercel API.

  • Navigate to the Edge Config tab of the Team or Personal Account where you would like to add the configuration
  • Click Create Store and type a name for your Edge Config in the dialog that opens and click Create. Let's use my_edge_config_id as a name
Note: The name can only contain alphanumeric letters, "_" and "-". It cannot exceed 32 characters.
  • On creation, you are taken to the my_edge_config_id config page. By default, a key-value pair of greeting: hello world is created

Your Edge Config is now ready to be used. You can also create a config at the project level.

You will need to create a read access token so that you can read data from your Edge Config via its endpoint with the fastest possible response times.

  • Make a POST request to the edge-config/token path of the API endpoint and include your Edge Config ID my_edge_config_id. Your request will require a Vercel API access token, passed as a value to the Authorization header as shown below:
    cURL
    curl -X 'POST' 'https://api.vercel.com/v1/edge-config/my_edge_config_id/token' \
         -H 'Authorization: Bearer your_vercel_api_token_here' \
         -H 'Content-Type: application/json; charset=utf-8' \
         -d $'{ "label": "my edge config token label" }'
    
    
    Note: Append the teamId query parameter to the endpoint if the config is scoped to a Vercel Team instead of your personal account.
  • Save the response that will be a JSON object with a "token" key that contains the value for the Edge Config read access token
    response
    { "token": "your_edge_config_read_access_token_here" }
    

Vercel creates a connection string as an environment variable (named EDGE_CONFIG by default) in the following situations:

  • when you link a project with an Edge Config
  • when you create an Edge Config from a project
Note: A connection string is not created when you create an Edge Config at the account level.

When you use the Edge Config, you call the same endpoint and pass the connection string so that the system knows what Edge Config to access.

Fetching Edge Config data from this endpoint gives you the fastest response times.

To construct a connection string for your Edge Config, add its Edge Config ID as a path and a valid Edge Config read access token as a query parameter to the following endpoint:

endpoint
'https://edge-config.vercel.com';

Your connection string should look like this:

connection-string
'https://edge-config.vercel.com/your_edge_config_id_here?token=your_edge_config_read_access_token_here';

Vercel will optimize your reads to be faster if you set the connection string as an environment variable.

The variable can be called anything, but our Edge Config client SDK will search for process.env.EDGE_CONFIG by default.

When you set the connection string as an environment variable, Vercel automatically optimizes all Edge Config reads from your application. Hard-coding your connection string into your application as a string will not allow Vercel to detect the URL and optimize your reads.

Check out our environment variables guide to learn how to set environment variables for your deployments on Vercel.

You can also create an Edge Config using the Vercel API.