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.
@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.
Writing Edge Config Items
Edge Config Items can be managed in two ways:
Keep in mind that Edge Config is built for very high read volume, but for infrequent writes.
Features
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:
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' };
Caught a Bug?
- Fork this repository to your own GitHub account and then clone it to your local device
- Link the package to the global module directory:
npm link
- 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
A note for Vite users
@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:
- You can populate
process.env
yourself using something like dotenv-expand
:
pnpm install --save-dev dotenv dotenv-expand
import dotenvExpand from 'dotenv-expand';
import { loadEnv, defineConfig } from 'vite';
export default defineConfig(({ mode }) => {
if (mode === 'development') {
const env = loadEnv(mode, process.cwd(), '');
dotenvExpand.expand({ parsed: env });
}
return {
...
};
});
- 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');