Getting started with Global Config

Global Config is a distributed key-value store that allows you to store and retrieve data on Vercel's global network, close to your users. It is designed for high performance and low latency, making it ideal for use cases such as feature flags, A/B testing, and dynamic configuration.

This guide will help you create a Global Config called hello_world_store at the project-level, through the Vercel dashboard. A token and environment variable GLOBAL_CONFIG, that stores the connection string, will be automatically created for you. You'll update the store with a key-value data pair and read the value of "greeting" from a local Next.js project.

• Install the Global Config SDK:
  pnpmyarnnpmbun

  Terminal

  pnpm i @vercel/global-config

  Terminal

  yarn add @vercel/global-config

  Terminal

  npm i @vercel/global-config

  Terminal

  bun add @vercel/global-config

• An existing project. This quickstart uses Next.js, but you can use any supported framework with Global Config storage
• Install or update to the latest version of Vercel CLI

pnpm i -g vercel@latest

yarn global add vercel@latest

npm i -g vercel@latest

bun add -g vercel@latest

1. Create a Global Config store

   Navigate to the Project you'd like to add a Global Config store to. Click on Storage, then click the Create Database button. Select Global Config and click Continue.

   Create a new store by typing hello_world_store under Global Config in the dialog that opens, and click Create.

   The name can only contain alphanumeric letters, "_" and "-". It cannot exceed 32 characters.

2. Review what was created

   Once created, select hello_world_store to see a summary of what was created for you. Notice the following:

   • If you select Project, you'll see that your project was connected to the Global Config by using an environment variable. If you go to your project's Settings > Environment Variables, you'll see the newly created environment variable.
   • If you select Tokens, you'll see a read access token. This token, along with your GLOBAL CONFIG ID, is used to create a connection string. This connection string is saved as the value of your GLOBAL_CONFIG environment variable. This enables you to use the SDK in your project to read the store's contents.

   If you're creating a project at the account-level, we won't automatically create a token, connection string, and environment variable until a project has been connected.

3. Add a key-value pair

   Under Items, add the following key-value pair and click Save Items:

   {
     "greeting": "hello world"
   }

   You can see more information about what can be stored in a Global Config in the limits documentation.

4. Connect your Vercel project

   Once you've created the store, you need to set up your project to read the contents of the store. This is detailed under Learn how to use this in code in the dashboard, but is described in the following steps in more detail.

   On your local machine, connect your Vercel Project. If you haven't already, install the Global Config SDK, as mentioned in prerequisites.

5. Pull the latest environment variables

   Using Vercel CLI, pull the latest environment variables, specifically GLOBAL_CONFIG, so that it's available to your project locally:

   terminal

   vercel env pull

6. Create a Middleware

   Create a Middleware for your project by creating a new file called middleware.js at the root of the project and if using Next.js, add the following code:

   middleware.ts

   import { NextResponse } from 'next/server';
   import { get } from '@vercel/global-config';
    
   export const config = { matcher: '/welcome' };
    
   export async function middleware() {
     const greeting = await get('greeting');
     return NextResponse.json(greeting);
   }

   middleware.js

   import { NextResponse } from 'next/server';
   import { get } from '@vercel/global-config';
    
   export const config = { matcher: '/welcome' };
    
   export async function middleware() {
     const greeting = await get('greeting');
     return NextResponse.json(greeting);
   }

   NextResponse.json requires at least Next v13.1 or enabling experimental.allowMiddlewareResponseBody in next.config.js.

7. Run your application locally

   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 Global Config store.

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

Now that you've created a Global Config store and read from it, you can explore the following:

• Creating the Global Config at the account level
• Creating a read access token
• Setting up a connection string
• Learn about the @vercel/global-config package
• Explore the SDK