@vercel/edge-config

What is @vercel/edge-config?

@vercel/edge-config is a package designed to manage configuration at the edge, allowing developers to dynamically control and update configuration settings for their applications without redeploying. This is particularly useful for feature flags, A/B testing, and other runtime configuration needs.

What are @vercel/edge-config's main functionalities?

Fetching Configuration

This feature allows you to fetch the current configuration settings from the edge. The `getConfig` function retrieves the configuration, which can then be used within your application.

const { getConfig } = require('@vercel/edge-config');

async function fetchConfig() {
  const config = await getConfig();
  console.log(config);
}

fetchConfig();

Setting Configuration

This feature allows you to update the configuration settings at the edge. The `setConfig` function takes a new configuration object and updates the settings accordingly.

const { setConfig } = require('@vercel/edge-config');

async function updateConfig(newConfig) {
  await setConfig(newConfig);
  console.log('Configuration updated');
}

updateConfig({ featureFlag: true });

Listening for Configuration Changes

This feature allows you to listen for changes in the configuration settings. The `onConfigChange` function takes a callback that is executed whenever the configuration is updated.

const { onConfigChange } = require('@vercel/edge-config');

onConfigChange((newConfig) => {
  console.log('Configuration changed:', newConfig);
});

Other packages similar to @vercel/edge-config

config

The `config` package is a popular choice for managing configuration settings in Node.js applications. It allows for configuration files to be organized by environment and provides a simple API for accessing these settings. Unlike @vercel/edge-config, it does not provide edge-specific features or dynamic updates without redeployment.

dotenv

The `dotenv` package is used to load environment variables from a `.env` file into `process.env`. It is widely used for managing configuration in Node.js applications. However, it lacks the dynamic and edge-specific capabilities of @vercel/edge-config.

feature-toggle

The `feature-toggle` package provides a way to manage feature flags in Node.js applications. It allows for enabling or disabling features based on configuration settings. While it offers some similar functionality to @vercel/edge-config, it does not provide the same level of integration with edge environments.

README

@vercel/edge-config

A client that lets you read Edge Config.

Installation

npm install @vercel/edge-config

Examples

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

Reading a value

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

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

Checking if a key exists

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

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

Reading all items

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

Returns all Edge Config items. Throws on invalid tokens, deleted edge configs or network errors.

Reading items in batch

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

Returns selected Edge Config items. Throws on invalid tokens, deleted edge configs or network errors.

Default behaviour

By default @vercel/edge-config will read from the Edge Config stored in process.env.EDGE_CONFIG.

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

Reading a value from a specific Edge Config

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

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

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

It returns the same get, getAll, has and digest functions as the default Edge 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 Edge Config Items

Edge Config Items can be managed in two ways:

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

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

Features

• Works in Edge Runtime, Node.js and in the browser

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/edge-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/edge-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/edge-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/edge-config';
import { trace } from '@opentelemetry/api';

setTracerProvider(trace);

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

Fetch cache

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

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

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

const edgeConfigClient = createClient(process.env.EDGE_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.

Notes

Do not mutate return values

Cloning objects in JavaScript can be slow. That's why the Edge 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 Edge 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.

Usage with Vite

@vercel/edge-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 {
    ...
  };
});

1. 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/edge-config';
+ import { EDGE_CONFIG } from '$env/static/private';

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

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/edge-config, just link it to the dependencies: npm link @vercel/edge-config. Instead of the default one from npm, Node.js will now use your clone of @vercel/edge-config!

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