Skip to Content

Integrations

Vercel

Mirror the datafile to Vercel Global Config, next to the middleware that reads it.

3 min read

Global Config — Edge Config until its 2026 rename — is a small store that is replicated to Vercel's edge. A Next.js middleware can read the datafile from it without a round trip to Improve, which is the one place Next.js does not cache the fetch for you.

Improve keeps the store in sync with the active datafile of each environment of a Space, in both formats: production, staging and develop for format 1, and production_f2, staging_f2 and develop_f2 for an SDK that buckets exclusion groups and holdouts. Drafts, finished and archived tests are not mirrored; those come from the API.

Watch out

Global Config is a paid Vercel feature: reads and writes count toward its usage. Improve only writes when the datafile changed, so an idle Space costs no writes.

Setting up

  1. Create a Vercel access token: Creating an access token. It can act on your whole Vercel account, so keep it in a password manager.
  2. In Improve, open Settings → Integrations, under Vercel Global Config, paste the token and press Connect.
  3. Pick the team the store belongs to, or Personal account. Improve creates the store obelism_improve_{spaceId} — or uses the one that is already there — and writes the current datafile.
  4. In Vercel, open your project's Storage, connect the obelism_improve_… store to the project (it adds a GLOBAL_CONFIG environment variable), and redeploy.

Connecting needs the admin role. The token is stored encrypted and is never shown again; Disconnect deletes the store in Vercel and forgets the token.

Deleting the Space, or its Organization, stops the syncing at once. Improve deletes the store in Vercel and forgets the token a day before the Space is removed for good, 30 days after it was deleted; restoring the Space in that last day brings it back without the connection, to connect again.

An edit reaches the store within a minute, and Vercel takes up to 10 seconds more to propagate it. Sync now on the same page writes immediately.

Using it

npm i @vercel/global-config

Read one environment with get, or all of them with getAll (one read):

import { getAll } from '@vercel/global-config'
import { ImproveServerSDK } from '@obelism/improve-sdk/server'
import type { ImproveConfiguration } from '@obelism/improve-sdk/types'

const environment = process.env.IMPROVE_ENVIRONMENT ?? 'production'
const state = process.env.IMPROVE_STATE ?? 'active'

// An SDK that buckets exclusion groups and holdouts reads format 2.
const key = `${environment}_f2`
const fromStore = (
	state === 'active' ? (await getAll())?.[key] : undefined
) as ImproveConfiguration | undefined

const improveSdk = new ImproveServerSDK({
	organizationId: process.env.IMPROVE_ORGANIZATION_ID!,
	spaceId: process.env.IMPROVE_SPACE_ID!,
	environment,
	token: process.env.IMPROVE_API_TOKEN!,
	...(fromStore && { config: fromStore }),
})

// Only needed when the store has no entry for this state (a draft, for
// instance): the API has every state.
if (!fromStore) await improveSdk.fetchConfig()

The value is the datafile for that environment: an ImproveConfiguration, exactly what fetchConfig returns. Pass it to loadConfig, into the constructor as above, or to the Next.js middleware — see Next.js + Vercel.

Limits

  • Depends on the space, not the organization. A store holds one Space's three environments. A second Space means a second store.
  • Active only. A test in any other state is read from the API. The dashboard's previews do that already.
  • Not counted as Config Requests. A site reading Global Config never reaches Improve, so the request cannot be counted. The plan's freeze still applies: the store is written with the same datafile /config serves, so a frozen Organization's store freezes too.

On this page

Marks in the margin

  • Note
  • Watch out
  • Updated

Scribes marked doubtful lines in the margin. That practice is called obelism.