@vercel/global-config

A client that lets you read Global Config (formerly known as Edge Config).

This package is a drop-in replacement for @vercel/edge-config.

Installation

npm install @vercel/global-config

Examples

You can use the methods below to read your Global Config given you have its Connection String stored in an Environment Variable called process.env.GLOBAL_CONFIG.

Reading a value

import { get } from '@vercel/global-config';
await get('someKey');

Returns the value if the key exists. Returns undefined if the key does not exist. Throws on invalid tokens, deleted global configs or network errors.

Checking if a key exists

import { has } from '@vercel/global-config';
await has('someKey');

Returns true if the key exists. Returns false if the key does not exist. Throws on invalid tokens, deleted global configs or network errors.

Reading all items

import { getAll } from '@vercel/global-config';
await getAll();

Returns all Global Config items. Throws on invalid tokens, deleted global configs or network errors.

Reading items in batch

import { getAll } from '@vercel/global-config';
await getAll(['keyA', 'keyB']);

Returns selected Global Config items. Throws on invalid tokens, deleted global configs or network errors.

Default behaviour

By default @vercel/global-config will read from the Global Config stored in process.env.GLOBAL_CONFIG, falling back to process.env.EDGE_CONFIG if process.env.GLOBAL_CONFIG is not defined.

The exported get, getAll, has and digest functions are bound to this default Global Config Client.

Reading a value from a specific Global Config

You can use createClient(connectionString) to read values from Global Configs other than the default one.

import { createClient } from '@vercel/global-config';
const edgeConfig = createClient(process.env.ANOTHER_GLOBAL_CONFIG);
await edgeConfig.get('someKey');

The createClient function connects to a any Global Config based on the provided Connection String.

It returns the same get, getAll, has and digest functions as the default Global Config Client exports.

Making a value mutable

By default, the value returned by get and getAll is immutable. Modifying the object might cause an error or other undefined behaviour.

In order to make the returned value mutable, you can use the exported function clone to safely clone the object and make it mutable.

Writing Global Config Items

Global Config Items can be managed in two ways:

• Using the Dashboard on vercel.com
• Using the Vercel API

Keep in mind that Global Config is built for very high read volume, but for infrequent writes.

Error Handling

• An error is thrown in case of a network error
• An error is thrown in case of an unexpected response

Edge Runtime Support

@vercel/global-config is compatible with the Edge Runtime. It can be used inside environments like Vercel Edge Functions as follows:

// Next.js (pages/api/edge.js) (npm i next@canary)
// Other frameworks (api/edge.js) (npm i -g vercel@canary)

import { get } from '@vercel/global-config';

export default (req) => {
  const value = await get("someKey")
  return new Response(`someKey contains value "${value})"`);
};

export const config = { runtime: 'edge' };

OpenTelemetry Tracing

The @vercel/global-config package makes use of the OpenTelemetry standard to trace certain functions for observability. In order to enable it, use the function setTracerProvider to set the TracerProvider that should be used by the SDK.

import { setTracerProvider } from '@vercel/global-config';
import { trace } from '@opentelemetry/api';

setTracerProvider(trace);

More verbose traces can be enabled by setting the GLOBAL_CONFIG_TRACE_VERBOSE environment variable to true.

Frameworks

Next.js

Cache Components

The Global Config SDK supports Cache Components out of the box. Since Global Config is a dynamic operation it always triggers dynamic mode unless you explicitly opt out as shown in the next section.

Fetch cache

By default the Global Config SDK will fetch with no-store, which triggers dynamic mode in Next.js (docs).

To use Global Config with static pages, pass the force-cache option:

import { createClient } from '@vercel/global-config';

const edgeConfigClient = createClient(process.env.GLOBAL_CONFIG, {
  cache: 'force-cache',
});

// then use the client as usual
edgeConfigClient.get('someKey');

Note This opts out of dynamic behavior, so the page might display stale values.

Nuxt, SvelteKit and other vite based frameworks

@vercel/global-config reads database credentials from the environment variables on process.env. In general, process.env is automatically populated from your .env file during development, which is created when you run vc env pull. However, Vite does not expose the .env variables on process.env.

You can fix this in one of following two ways:

1. You can populate process.env yourself using something like dotenv-expand:

pnpm install --save-dev dotenv dotenv-expand

// vite.config.js
import dotenvExpand from 'dotenv-expand';
import { loadEnv, defineConfig } from 'vite';

export default defineConfig(({ mode }) => {
  // This check is important!
  if (mode === 'development') {
    const env = loadEnv(mode, process.cwd(), '');
    dotenvExpand.expand({ parsed: env });
  }

  return {
    ...
  };
});

2. You can provide the credentials explicitly, instead of relying on a zero-config setup. For example, this is how you could create a client in SvelteKit, which makes private environment variables available via $env/static/private:

import { createClient } from '@vercel/global-config';
+ import { GLOBAL_CONFIG } from '$env/static/private';

- const edgeConfig = createClient(process.env.ANOTHER_GLOBAL_CONFIG);
+ const edgeConfig = createClient(GLOBAL_CONFIG);
await edgeConfig.get('someKey');

Notes

Do not mutate return values

Cloning objects in JavaScript can be slow. That's why the Global Config SDK uses an optimization which can lead to multiple calls reading the same key all receiving a reference to the same value.

For this reason the value read from Global Config should never be mutated, otherwise they could affect other parts of the code base reading the same key, or a later request reading the same key.

If you need to modify, see the clone function described here.

Caught a Bug?

1. Fork this repository to your own GitHub account and then clone it to your local device
2. Link the package to the global module directory: npm link
3. Within the module you want to test your local development instance of @vercel/global-config, just link it to the dependencies: npm link @vercel/global-config. Instead of the default one from npm, Node.js will now use your clone of @vercel/global-config!

As always, you can run the tests using: npm test