Split

Next.js (/app)

Choose a framework to optimize documentation to:

Using Global Config with Split

This guide will help you get started with using Vercel's Split integration with Global Config. This integration allows you to use Global Config as a configuration source for your Split feature flags.

The Split Global Config integration is available in Beta on all plans

Split is a feature flag provider that tracks event data, enabling you to release features, target them to audiences, and measure their impact on customer experience metrics securely.

The Split Global Config integration enables you to write your Split rollout plan to a Global Config. Doing so will allow you to evaluate feature flags at ultra-low latency with Vercel's CDN while tracking events and impressions data with Split.

Prerequisites

Before using this integration, you should have:

The latest version of Vercel CLI. To check your version, use vercel --version. To install or update Vercel CLI, use:
Terminal
pnpm i -g vercel@latest
Terminal
yarn global add vercel@latest
Terminal
npm i -g vercel@latest
Terminal
bun add -g vercel@latest
A project. If you don't have one, you can run the following terminal commands to create a Next project:

Terminal

pnpm create next-app@latest

Terminal

yarn create next-app@latest

Terminal

npx create-next-app@latest

Terminal

bunx create-next-app@latest

A Vercel project. If you don't have one, see Creating a Project
A Global Config. If you don't have one, follow the Global Config quickstart

The Global Config SDK:

Terminal

pnpm i @vercel/global-config

Terminal

yarn add @vercel/global-config

Terminal

npm i @vercel/global-config

Terminal

bun add @vercel/global-config

To configure this integration, Split Admin access (Split Admin users can add feature flags and segments, and edit them at will) is required.

Set up the Split integration
Visit the Split page in the Vercel Integration Marketplace and select the Add Integration button. From the Integration dialog:
1. Select a Vercel team and project to connect the integration to
2. Log into Split
3. Select the Split Environment you want to use
4. Select an existing Global Config or create a new one
5. Copy the Global Config item key provided on this page. You'll need it to add it to your Environment Variables
You can also find your Global Config Split item key in your dashboard on Vercel. In the Integrations section in the sidebar, select Manage, then select Configure on the integration page. You should see the item key on the page that opens.
Create your feature flags
If you already have existing feature flags, you can skip this step and use those. In this example, we'll create one called New_Marketing_Page. You can set the user targeting to Joe and Bobby.
To create a feature flag in Split:
1. Log into your Split management console and select the workspace icon near the top-left of the page
2. In the sidebar, under Target, select Feature flags. Add the name New_Marketing_Page, and set the traffic type to user. Select Create to finish
3. With your feature flag created, select the feature flag and open Definition in the sidebar. Select Initiate Environment to configure your flag
4. Add valid users to the feature flag
5. Scroll down to Targeting and select Add new individual target
6. Under To user, add any username you want to test. This example uses Joe.
7. Select Add new individual target, then set the Description option to off. Add another username under To user. This example uses Bobby
8. Select Review Changes, then Create to finish
Next, you need to add your credentials to your project's local environment to use the Split integration in your code.
Get your credentials
Next, you'll add the following credentials to your Vercel project:
- SPLIT_SDK_CLIENT_API_KEY
- EDGE_CONFIG_SPLIT_ITEM_KEY
- GLOBAL_CONFIG
To add environment variables to your project, visit your Vercel dashboard and select the project you want to use the Split integration with. Then select Settings > Environment Variables.
To get your Split client-side API keys:
1. Log into your Split management console and select the workspace icon near the top-left of the page
2. In the list of options that appears, select Admin Settings, then navigate to API Keys -> SDK API Keys
3. Copy the client-side keys associated with the workspace and environment you're using
To add your Global Config Split item key, if you didn't copy it after setting up the integration on Vercel:
1. Visit your dashboard on Vercel
2. In the Integrations section in the sidebar, select Manage
3. On the integration page, select Configure
4. You should see the item key on the page that opens. Copy it
To add your Global Config's connection string to your project:
1. Visit your project's page in the dashboard
2. Open Storage in the sidebar. Select Connect Store and select the Global Config associated with your Split integration. The GLOBAL_CONFIG environment variable will be set automatically.
Now you're ready to use the Split Global Config integration in your code.

Use the Split integration in your code

Open your project's code on your local machine and do the following:

Install Split's Browser SDK, Vercel integration utilities, and Vercel's Global Config SDK:

Terminal

pnpm i @splitsoftware/splitio-browserjs @splitsoftware/vercel-integration-utils @vercel/global-config

Terminal

yarn add @splitsoftware/splitio-browserjs @splitsoftware/vercel-integration-utils @vercel/global-config

Terminal

npm i @splitsoftware/splitio-browserjs @splitsoftware/vercel-integration-utils @vercel/global-config

Terminal

bun add @splitsoftware/splitio-browserjs @splitsoftware/vercel-integration-utils @vercel/global-config

Create an API route in your project. The following example fetches a treatement based on which user is visiting. You can specify the user by appending ?userKey=Joe or ?userKey=Bobby to the URL when visiting the route:

app/api/marketing-example/route.ts

import {
  SplitFactory,
  PluggableStorage,
  ErrorLogger,
} from '@splitsoftware/splitio-browserjs';
import { EdgeConfigWrapper } from '@splitsoftware/vercel-integration-utils';
import { createClient } from '@vercel/global-config';
 
export async function GET(request: Request) {
  const { EDGE_CONFIG_SPLIT_ITEM_KEY, SPLIT_SDK_CLIENT_API_KEY } = process.env;
 
  if (!SPLIT_SDK_CLIENT_API_KEY || !EDGE_CONFIG_SPLIT_ITEM_KEY)
    return new Response(
      `Failed to find your SDK Key (${SPLIT_SDK_CLIENT_API_KEY})
      or item key ${EDGE_CONFIG_SPLIT_ITEM_KEY}`,
    );
 
  const edgeConfigClient = createClient(process.env.GLOBAL_CONFIG);
  const { searchParams } = new URL(request.url);
  const userKey = searchParams.get('userKey') || 'anonymous';
  const client = SplitFactory({
    core: {
      authorizationKey: SPLIT_SDK_CLIENT_API_KEY,
      key: userKey,
    },
    mode: 'consumer_partial',
    storage: PluggableStorage({
      wrapper: EdgeConfigWrapper({
        // The Global Config item key where Split stores
        // feature flag definitions
        edgeConfigItemKey: EDGE_CONFIG_SPLIT_ITEM_KEY,
        // The Global Config client
        edgeConfig: edgeConfigClient,
      }),
    }),
    // Disable or keep only ERROR log level in production,
    // to minimize performance impact
    debug: ErrorLogger(),
  }).client();
 
  await new Promise((resolve) => {
    client.on(client.Event.SDK_READY, () => resolve);
    client.on(client.Event.SDK_READY_TIMED_OUT, () => resolve);
  });
 
  // Replace this with the feature flag you want
  const FEATURE_FLAG = 'New_Marketing_Page';
  const treatment = await client.getTreatment(FEATURE_FLAG);
 
  // Must await in app-router; waitUntil() is not
  // yet supported
  await client.destroy();
 
  // treatment will be 'control' if the SDK timed out
  if (treatment == 'control') return new Response('Control marketing page');
 
  return treatment === 'on'
    ? new Response('New marketing page')
    : new Response('Old marketing page');
}

app/api/marketing-example/route.ts

import {
  SplitFactory,
  PluggableStorage,
  ErrorLogger,
} from '@splitsoftware/splitio-browserjs';
import { EdgeConfigWrapper } from '@splitsoftware/vercel-integration-utils';
import { createClient } from '@vercel/global-config';
 
export async function GET(request: Request) {
  const { EDGE_CONFIG_SPLIT_ITEM_KEY, SPLIT_SDK_CLIENT_API_KEY } = process.env;
 
  if (!SPLIT_SDK_CLIENT_API_KEY || !EDGE_CONFIG_SPLIT_ITEM_KEY)
    return new Response(
      `Failed to find your SDK Key (${SPLIT_SDK_CLIENT_API_KEY})
      or item key ${EDGE_CONFIG_SPLIT_ITEM_KEY}`,
    );
 
  const edgeConfigClient = createClient(process.env.GLOBAL_CONFIG);
  const { searchParams } = new URL(request.url);
  const userKey = searchParams.get('userKey') || 'anonymous';
  const client = SplitFactory({
    core: {
      authorizationKey: SPLIT_SDK_CLIENT_API_KEY,
      key: userKey,
    },
    mode: 'consumer_partial',
    storage: PluggableStorage({
      wrapper: EdgeConfigWrapper({
        // The Global Config item key where Split stores
        // feature flag definitions
        edgeConfigItemKey: EDGE_CONFIG_SPLIT_ITEM_KEY,
        // The Global Config client
        edgeConfig: edgeConfigClient,
      }),
    }),
    // Disable or keep only ERROR log level in production,
    // to minimize performance impact
    debug: ErrorLogger(),
  }).client();
 
  await new Promise((resolve) => {
    client.on(client.Event.SDK_READY, () => resolve);
    client.on(client.Event.SDK_READY_TIMED_OUT, () => resolve);
  });
 
  // Replace this with the feature flag you want
  const FEATURE_FLAG = 'New_Marketing_Page';
  const treatment = await client.getTreatment(FEATURE_FLAG);
 
  // Must await in app-router; waitUntil() is not
  // yet supported
  await client.destroy();
 
  // treatment will be 'control' if the SDK timed out
  if (treatment == 'control') return new Response('Control marketing page');
 
  return treatment === 'on'
    ? new Response('New marketing page')
    : new Response('Old marketing page');
}

app/api/marketing-example/route.js

import {
  SplitFactory,
  PluggableStorage,
  ErrorLogger,
} from '@splitsoftware/splitio-browserjs';
import { EdgeConfigWrapper } from '@splitsoftware/vercel-integration-utils';
import { createClient } from '@vercel/global-config';
 
export async function GET(request) {
  const { EDGE_CONFIG_SPLIT_ITEM_KEY, SPLIT_SDK_CLIENT_API_KEY } = process.env;
 
  if (!SPLIT_SDK_CLIENT_API_KEY || !EDGE_CONFIG_SPLIT_ITEM_KEY)
    return new Response(
      `Failed to find your SDK Key (${SPLIT_SDK_CLIENT_API_KEY})
      or item key ${EDGE_CONFIG_SPLIT_ITEM_KEY}`,
    );
 
  const edgeConfigClient = createClient(process.env.GLOBAL_CONFIG);
  const { searchParams } = new URL(request.url);
  const userKey = searchParams.get('userKey') || 'anonymous';
  const client = SplitFactory({
    core: {
      authorizationKey: SPLIT_SDK_CLIENT_API_KEY,
      key: userKey,
    },
    mode: 'consumer_partial',
    storage: PluggableStorage({
      wrapper: EdgeConfigWrapper({
        // The Global Config item key where Split stores
        // feature flag definitions
        edgeConfigItemKey: EDGE_CONFIG_SPLIT_ITEM_KEY,
        // The Global Config client
        edgeConfig: edgeConfigClient,
      }),
    }),
    // Disable or keep only ERROR log level in production,
    // to minimize performance impact
    debug: ErrorLogger(),
  }).client();
 
  await new Promise((resolve) => {
    client.on(client.Event.SDK_READY, () => resolve);
    client.on(client.Event.SDK_READY_TIMED_OUT, () => resolve);
  });
 
  // Replace this with the feature flag you want
  const FEATURE_FLAG = 'New_Marketing_Page';
  const treatment = await client.getTreatment(FEATURE_FLAG);
 
  // Must await in app-router; waitUntil() is not
  // yet supported
  await client.destroy();
 
  // treatment will be 'control' if the SDK timed out
  if (treatment == 'control') return new Response('Control marketing page');
 
  return treatment === 'on'
    ? new Response('New marketing page')
    : new Response('Old marketing page');
}

pages/api/marketing-example.ts

import {
  SplitFactory,
  PluggableStorage,
  ErrorLogger,
} from '@splitsoftware/splitio-browserjs';
import { EdgeConfigWrapper } from '@splitsoftware/vercel-integration-utils';
import { createClient } from '@vercel/global-config';
import { NextFetchEvent } from 'next/server';
 
export default async function handler(
  request: Request,
  context: NextFetchEvent,
) {
  const { EDGE_CONFIG_SPLIT_ITEM_KEY, SPLIT_SDK_CLIENT_API_KEY } = process.env;
 
  if (!SPLIT_SDK_CLIENT_API_KEY || !EDGE_CONFIG_SPLIT_ITEM_KEY)
    return new Response(
      `Failed to find your SDK Key (${SPLIT_SDK_CLIENT_API_KEY})
      or item key ${EDGE_CONFIG_SPLIT_ITEM_KEY}`,
    );
 
  const edgeConfigClient = createClient(process.env.GLOBAL_CONFIG);
  const { searchParams } = new URL(request.url);
  const userKey = searchParams.get('userKey') || 'anonymous';
  const client = SplitFactory({
    core: {
      authorizationKey: SPLIT_SDK_CLIENT_API_KEY,
      key: userKey,
    },
    mode: 'consumer_partial',
    storage: PluggableStorage({
      wrapper: EdgeConfigWrapper({
        // The Global Config item key where Split stores
        // feature flag definitions
        edgeConfigItemKey: EDGE_CONFIG_SPLIT_ITEM_KEY,
        // The Global Config client
        edgeConfig: edgeConfigClient,
      }),
    }),
    // Disable or keep only ERROR log level in production,
    // to minimize performance impact
    debug: ErrorLogger(),
  }).client();
 
  // Wait until
  await new Promise((resolve) => {
    client.on(client.Event.SDK_READY, () => resolve);
    client.on(client.Event.SDK_READY_TIMED_OUT, () => resolve);
  });
 
  // Replace this with the feature flag you want
  const FEATURE_FLAG = 'New_Marketing_Page';
  const treatment = await client.getTreatment(FEATURE_FLAG);
 
  // Must await in app-router; waitUntil() is not
  // yet supported
 
  context.waitUntil(client.destroy());
  // treatment will be 'control' if the SDK timed out
  if (treatment == 'control') return new Response('Control marketing page');
 
  return treatment === 'on'
    ? new Response('New marketing page')
    : new Response('Old marketing page');
}

pages/api/marketing-example.js

import {
  SplitFactory,
  PluggableStorage,
  ErrorLogger,
} from '@splitsoftware/splitio-browserjs';
import { EdgeConfigWrapper } from '@splitsoftware/vercel-integration-utils';
import { createClient } from '@vercel/global-config';
 
export default async function handler(request, context) {
  const { EDGE_CONFIG_SPLIT_ITEM_KEY, SPLIT_SDK_CLIENT_API_KEY } = process.env;
 
  if (!SPLIT_SDK_CLIENT_API_KEY || !EDGE_CONFIG_SPLIT_ITEM_KEY)
    return new Response(
      `Failed to find your SDK Key (${SPLIT_SDK_CLIENT_API_KEY})
      or item key ${EDGE_CONFIG_SPLIT_ITEM_KEY}`,
    );
 
  const edgeConfigClient = createClient(process.env.GLOBAL_CONFIG);
  const { searchParams } = new URL(request.url);
  const userKey = searchParams.get('userKey') || 'anonymous';
  const client = SplitFactory({
    core: {
      authorizationKey: SPLIT_SDK_CLIENT_API_KEY,
      key: userKey,
    },
    mode: 'consumer_partial',
    storage: PluggableStorage({
      wrapper: EdgeConfigWrapper({
        // The Global Config item key where Split stores
        // feature flag definitions
        edgeConfigItemKey: EDGE_CONFIG_SPLIT_ITEM_KEY,
        // The Global Config client
        edgeConfig: edgeConfigClient,
      }),
    }),
    // Disable or keep only ERROR log level in production,
    // to minimize performance impact
    debug: ErrorLogger(),
  }).client();
 
  // Wait until
  await new Promise((resolve) => {
    client.on(client.Event.SDK_READY, () => resolve);
    client.on(client.Event.SDK_READY_TIMED_OUT, () => resolve);
  });
 
  // Replace this with the feature flag you want
  const FEATURE_FLAG = 'New_Marketing_Page';
  const treatment = await client.getTreatment(FEATURE_FLAG);
 
  // Must await in app-router; waitUntil() is not
  // yet supported
 
  context.waitUntil(client.destroy());
  // treatment will be 'control' if the SDK timed out
  if (treatment == 'control') return new Response('Control marketing page');
 
  return treatment === 'on'
    ? new Response('New marketing page')
    : new Response('Old marketing page');
}

/api/marketing-example.ts

import {
  SplitFactory,
  PluggableStorage,
  ErrorLogger,
} from '@splitsoftware/splitio-browserjs';
import { EdgeConfigWrapper } from '@splitsoftware/vercel-integration-utils';
import { RequestContext } from '@vercel/edge';
import { createClient } from '@vercel/global-config';
 
export default async function handler(
  request: Request,
  context: RequestContext,
) {
  const { EDGE_CONFIG_SPLIT_ITEM_KEY, SPLIT_SDK_CLIENT_API_KEY } = process.env;
 
  if (!SPLIT_SDK_CLIENT_API_KEY || !EDGE_CONFIG_SPLIT_ITEM_KEY)
    return new Response(
      `Failed to find your SDK Key (${SPLIT_SDK_CLIENT_API_KEY})
      or item key ${EDGE_CONFIG_SPLIT_ITEM_KEY}`,
    );
 
  const edgeConfigClient = createClient(process.env.GLOBAL_CONFIG);
  const { searchParams } = new URL(request.url);
  const userKey = searchParams.get('userKey') || 'anonymous';
  const client = SplitFactory({
    core: {
      authorizationKey: SPLIT_SDK_CLIENT_API_KEY,
      key: userKey,
    },
    mode: 'consumer_partial',
    storage: PluggableStorage({
      wrapper: EdgeConfigWrapper({
        // The Global Config item key where Split stores
        // feature flag definitions
        edgeConfigItemKey: EDGE_CONFIG_SPLIT_ITEM_KEY,
        // The Global Config client
        edgeConfig: edgeConfigClient,
      }),
    }),
    // Disable or keep only ERROR log level in production,
    // to minimize performance impact
    debug: ErrorLogger(),
  }).client();
 
  // Wait until
  await new Promise((resolve) => {
    client.on(client.Event.SDK_READY, () => resolve);
    client.on(client.Event.SDK_READY_TIMED_OUT, () => resolve);
  });
 
  // Replace this with the feature flag you want
  const FEATURE_FLAG = 'New_Marketing_Page';
  const treatment = await client.getTreatment(FEATURE_FLAG);
 
  // Must await in app-router; waitUntil() is not
  // yet supported
 
  context.waitUntil(client.destroy());
  // treatment will be 'control' if the SDK timed out
  if (treatment == 'control') return new Response('Control marketing page');
 
  return treatment === 'on'
    ? new Response('New marketing page')
    : new Response('Old marketing page');
}

pages/api/marketing-example.js

  SplitFactory,
import {
  PluggableStorage,
  ErrorLogger,
} from '@splitsoftware/splitio-browserjs';
import { EdgeConfigWrapper } from '@splitsoftware/vercel-integration-utils';
import { createClient } from '@vercel/global-config';
 
export default async function handler(request, context) {
  const { EDGE_CONFIG_SPLIT_ITEM_KEY, SPLIT_SDK_CLIENT_API_KEY } = process.env;
 
  if (!SPLIT_SDK_CLIENT_API_KEY || !EDGE_CONFIG_SPLIT_ITEM_KEY)
    return new Response(
      `Failed to find your SDK Key (${SPLIT_SDK_CLIENT_API_KEY})
      or item key ${EDGE_CONFIG_SPLIT_ITEM_KEY}`,
    );
 
  const edgeConfigClient = createClient(process.env.GLOBAL_CONFIG);
  const { searchParams } = new URL(request.url);
  const userKey = searchParams.get('userKey') || 'anonymous';
  const client = SplitFactory({
    core: {
      authorizationKey: SPLIT_SDK_CLIENT_API_KEY,
      key: userKey,
    },
    mode: 'consumer_partial',
    storage: PluggableStorage({
      wrapper: EdgeConfigWrapper({
        // The Global Config item key where Split stores
        // feature flag definitions
        edgeConfigItemKey: EDGE_CONFIG_SPLIT_ITEM_KEY,
        // The Global Config client
        edgeConfig: edgeConfigClient,
      }),
    }),
    // Disable or keep only ERROR log level in production,
    // to minimize performance impact
    debug: ErrorLogger(),
  }).client();
 
  // Wait until
  await new Promise((resolve) => {
    client.on(client.Event.SDK_READY, () => resolve);
    client.on(client.Event.SDK_READY_TIMED_OUT, () => resolve);
  });
 
  // Replace this with the feature flag you want
  const FEATURE_FLAG = 'New_Marketing_Page';
  const treatment = await client.getTreatment(FEATURE_FLAG);
 
  // Must await in app-router; waitUntil() is not
  // yet supported
 
  context.waitUntil(client.destroy());
  // treatment will be 'control' if the SDK timed out
  if (treatment == 'control') return new Response('Control marketing page');
 
  return treatment === 'on'
    ? new Response('New marketing page')
    : new Response('Old marketing page');
}

Test your code
1. Start a local development server. If you're using Vercel CLI, enter the following command in the terminal:
terminal
```
vercel dev
```
1. Navigate to http://localhost:3000/api/split-example?userKey=Joe. You should see either New marketing page or Old marketing page based on how your feature flags are configured in Split
  - Try changing the userKey search param's value to Bobby, or deleting it altogether, to see different responses when you visit the route

Next steps

Now that you have set up the Split Global Config integration, you can explore the following topics to learn more:

Last updated August 11, 2026

Cross-link map: Using Global Config with Split (/docs/global-config/global-config-integrations/split-global-config)

From the Vercel docs graph (built 2026-09-15T06:10:09.927Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.json

Semantically closest pages

Client Uploads with Vercel Blob — Learn how to upload files larger than 4.5 MB directly from the browser to Vercel Blob
Routing Middleware API — Learn how you can use Routing Middleware, code that executes before a request is processed on a site, to provide speed a
Advanced Web Analytics Config with @vercel/analytics — With the @vercel/analytics npm package, you are able to configure your application to send analytics data to Vercel.
Next.js on Vercel — Vercel is the native Next.js platform, designed to enhance the Next.js experience.
How to use Next.js as a backend for your frontend — Learn how to use Next.js as a backend framework

This page links to (6)

Vercel CLI Overview — Learn how to use the Vercel command-line interface \(CLI\) to manage and configure your Vercel Projects from the command
Getting started with Global Config — Learn how to create a Global Config store and read from it in your project.
Managing Global Configs with the Dashboard — Learn how to create, view and update your Global Configs and the data inside them in your Vercel Dashboard at the Hobby
Global Config Limits and pricing — Learn about the Global Configs limits and pricing based on account plans.
@vercel/global-config — The Global Config client SDK is the most ergonomic way to read data from Global Configs. Learn how to set up the SDK so
Projects overview — A project is the application that you have deployed to Vercel.

Pages that link here (1)

By site: vercel-docs (1)

Using Global Config with an integration — Learn how to use Global Config with popular A/B testing and feature flag service integrations.

LaunchDarkly

Statsig

Was this helpful?

Build with AI

Deploy & scale

Operate & protect

Resources

Using Global Config with Split

Prerequisites

Set up the Split integration

Create your feature flags

Get your credentials

Use the Split integration in your code

Test your code

Next steps

Cross-link map: Using Global Config with Split (/docs/global-config/global-config-integrations/split-global-config)

Semantically closest pages

This page links to (6)

Pages that link here (1)

Cross-link map: Using Global Config with Split (/docs/global-config/global-config-integrations/split-global-config)

Semantically closest pages

This page links to (6)

Pages that link here (1)