Next.js SDK (Vercel Flags)

This documentation is intended for implementing the GrowthBook adapter for Vercel's Flags SDK in Next.js back-end or hybrid environments. For front-end-only GrowthBook implementations, please see our React docs.

Next.js SDK Resources

v0.1.0

adapter-growthbooknpmNext.js Flags SDK example appGet help on Slack

Installation

Install with a package manager

npm

npm install --save @flags-sdk/growthbook

Yarn

yarn add @flags-sdk/growthbook

pnpm

pnpm add @flags-sdk/growthbook

Adapter Usage

Import the Default Adapter

A default adapter is available for use, assuming the appropriate environment variables are set

import { growthbookAdapter } from '@flags-sdk/growthbook';

Environment Variables

The default adapter automatically uses following environment variables:

# Required
GROWTHBOOK_CLIENT_KEY="sdk-abc123"

# Optional for cloud customers, required for self-hosted
GROWTHBOOK_API_HOST="https://api.your-growthbook-instance.io"

# Optional, self-hosted only
GROWTHBOOK_APP_ORIGIN="https://app.your-growthbook-instance.io" # For Flags Explorer integration


# Edge Config (Optional)

EXPERIMENTATION_CONFIG="your-vercel-edge-config" # for native Vercel integrations
# or
GROWTHBOOK_EDGE_CONNECTION_STRING="your-edge-connection-string"

# Optional: Edge Config is keyed by `clientKey` by default. To override, set:
GROWTHBOOK_EDGE_CONFIG_ITEM_KEY="gb_payload"

Create a Custom Adapter

You can provide custom configuration by using createGrowthBookAdapter:

import { createGrowthBookAdapter } from '@flags-sdk/growthbook';

const myGrowthBookAdapter = createGrowthBookAdapter({
  clientKey: process.env.GROWTHBOOK_CLIENT_KEY!,
  apiHost: process.env.GROWTHBOOK_API_HOST, // optional
  appOrigin: process.env.GROWTHBOOK_APP_ORIGIN, // optional
  edgeConfig: {
    connectionString: process.env.GROWTHBOOK_EDGE_CONNECTION_STRING!,
    itemKey: process.env.GROWTHBOOK_EDGE_CONFIG_ITEM_KEY, // optional
  },
  trackingCallback: (experiment, result) => {
    // Back-end exposure logging
  },
  clientOptions: {}, // GrowthBook ClientOptions (optional)
  initOptions: {},   // GrowthBook InitOptions (optional)
  stickyBucketService: undefined, // Optional
});

User Identification

GrowthBook uses Attributes to evaluate feature flags and experiments. You should write an identify function providing these Attributes to GrowthBook flags:

import { dedupe, flag } from 'flags/next';
import type { Identify } from 'flags';
import { growthbookAdapter, type Attributes } from '@flags-sdk/growthbook';

const identify = dedupe((async ({ headers, cookies }) => {
  return {
    id: cookies.get('user_id')?.value,
    // etc...
  };
}) satisfies Identify<Attributes>);

export const myFeatureFlag = flag({
  key: 'my_feature_flag',
  identify,
  adapter: growthbookAdapter.feature<boolean>(),
});

Dedupe is used above to ensure that the Attributes are computed once per request.

Adapter Methods and Properties

.feature<T>()

This method implements the Adapter interface for a GrowthBook feature. Typically flag definitions are applied in single file (e.g. flags.ts).

export const myFlag = flag({
  key: 'my_flag',
  adapter: growthbookAdapter.feature<string>(),
  defaultValue: "default",
  identify,
});

You may optionally pass in an options object for further customization (ex: feature({ exposureLogging: false }))

Option	Default	Description
exposureLogging	true	Enable/disable exposure logging.

.initialize()

Initializes the GrowthBook SDK. This is done on-demand when a growthbook flag is evaluated, and is not required to be called manually:

const growthbookClient = await growthbookAdapter.initialize();

.setTrackingCallback()

Set a back-end callback to handle experiment exposures. This allows you to log exposures to your analytics platform. Typically this is done in the same file where your flags are defined (e.g. flags.ts).

import { growthbookAdapter } from '@flags-sdk/growthbook';
import { after } from 'next/server';

growthbookAdapter.setTrackingCallback((experiment, result) => {
  // Safely fire and forget async calls (Next.js)
  after(async () => {
    console.log('Viewed Experiment', {
      experimentId: experiment.key,
      variationId: result.key,
    });
  });
});

Front-end experiment tracking is also supported, although it requires additional manual setup. See client-side tracking for more information.

.setStickyBucketService()

Sticky bucketing ensures that users see the same experiment variant, even when user session, user login status, or experiment parameters change. See the Sticky Bucketing docs for more information. If your organization and experiment supports sticky bucketing, you must implement an instance of the StickyBucketService to use Sticky Bucketing.

import { growthbookAdapter } from '@flags-sdk/growthbook';
import { RedisStickyBucketService } from '@growthbook/growthbook';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_CONNECTION_URL);
const redisStickyBucketService = new RedisStickyBucketService({ redis });

growthbookAdapter.setStickyBucketService(redisStickyBucketService);

.growthbook

You may access the underlying GrowthBook instance. Specifically, our Flags SDK adapter wraps the GrowthBookClient class read more. All user evaluation options (attributes, tracking callbacks, sticky buckets) are applied at the userContext level (not globally).

.stickyBucketService

If you have set a sticky bucket service, you may retrieve its instance.

Edge Config

The adapter can load your SDK payload from Vercel's Edge Config to lower the latency of feature flag evaluation:

• Set GROWTHBOOK_EDGE_CONNECTION_STRING (or EXPERIMENTATION_CONFIG if installed through the Vercel Marketplace) in your environment. Optionally set GROWTHBOOK_EDGE_CONFIG_ITEM_KEY to override the default key name (defaults to your client key).
• Or pass edgeConfig directly to the adapter.

If Edge Config is not set, the adapter will fetch configuration from GrowthBook's API.

Configuring a SDK Webhook

1. To automatically populate the Edge Config whenever your feature definitions change, create a SDK Webhook on the same SDK Connection that you are using for the Next.js integration.ts

2. Select "Vercel Edge Config" as the webhook type and fill out the following fields:

• Vercel Edge Config ID (begins with ecfg_)
• Team ID (optional)
• Vercel API Token (see Vercel → Account Settings → Tokens)

Under the hood, the webhook is being configured with the following properties. If you need to change any of these settings for any reason, you can always edit the webhook.

• Endpoint URL is being set to

  https://api.vercel.com/v1/edge-config/{edge_config_id}/items
• Method is being set to PATCH
• An Authorization: Bearer token header is being added with your Vercel API Token
• The Payload format is being set to Vercel Edge Config

note

Vercel's Edge Config is subject to storage size limitations. If your SDK payload is excessively large, you may not be able to populate the your Edge Config. Read more about limitations here.

Additional Configuration

• Initialization: The adapter auto-initializes when a flag is evaluated. To pre-initialize, call initialize() manually.
• Exposure Logging: By default, exposures are logged when flags are evaluated. You can disable this with exposureLogging: false or provide a custom tracking callback (applicable to back-end tracking only).

Flags Explorer Integration

To expose GrowthBook data to the Flags Explorer, use the getProviderData function in your API route:

import { getProviderData, createFlagsDiscoveryEndpoint } from 'flags/next';
import { getProviderData as getGrowthBookProviderData } from '@flags-sdk/growthbook';
import { mergeProviderData } from 'flags';
import * as flags from '../../../../flags';

export const GET = createFlagsDiscoveryEndpoint(async (request) => {
  return mergeProviderData([
    getProviderData(flags),
    getGrowthBookProviderData({
      // Add any required options here
    }),
  ]);
});

You will also need to provide a FLAGS_SECRET environment variable. See Vercel's Flags Explorer guide.

Client-side Tracking

When using the Flags SDK, we strongly encourage using server-side tracking when possible. However, some event trackers are best suited for client-side implementation. Additionally, some user attributes may only be available in a front-end context.

We recommend implementing client-side tracking using some glue components:

1. A <GrowthbookTracking> server component which takes a list of evaluated feature ids and prepares the data necessary to hydrate the tracking calls for the client. It embeds a <GrowthbookTrackingClient> client component.
2. A <GrowthbookTrackingClient> client component responsible for executing and deduping your tracking calls in the browser. You will need to define a client-side tracking callback within this component. Under the hood, this component works by replaying all of the experiment evaluations in a client context.
3. You must include <GrowthbookTracking> in any component which evaluates a feature flag (or specifically: all referenced flags that may trigger experiment tracking callbacks).

1. <GrowthbookTracking> components/growthbook/client-side-tracking/growthbook-tracking.tsx

import {
  growthbookAdapter,
  type Attributes,
  type StickyAssignmentsDocument,
} from '@flags-sdk/growthbook';
import { identify } from '@/lib/identify';
import { GrowthbookTrackingClient } from './client';

export async function GrowthbookTracking({ featureIds }: { featureIds: string[] }) {
  // The GrowthBook SDK must be ready before tracking
  await growthbookAdapter.initialize();
  const payload = growthbookAdapter.growthbook.getDecryptedPayload();
  const attributes: Attributes = await identify();

  // If using sticky bucketing, extract the docs for client side hydration
  let stickyBucketAssignmentDocs: Record<string, StickyAssignmentsDocument> | undefined;
  if (growthbookAdapter.stickyBucketService) {
    const ctx = await growthbookAdapter.growthbook.applyStickyBuckets(
      { attributes },
      growthbookAdapter.stickyBucketService
    );
    stickyBucketAssignmentDocs = ctx.stickyBucketAssignmentDocs;
  }

  return (
    <GrowthbookTrackingClient
      featureIds={featureIds}
      attributes={attributes}
      payload={payload}
      stickyBucketAssignmentDocs={stickyBucketAssignmentDocs}
    />
  );
}

2. <GrowthbookTrackingClient> components/growthbook/client-side-tracking/client.tsx

'use client';

import {
  GrowthBookClient,
  type Attributes,
  type TrackingCallback,
  type StickyAssignmentsDocument,
  type FeatureApiResponse,
  type UserContext,
} from '@growthbook/growthbook';
import { useEffect } from 'react';

// Define your client-side tracking callback:
// You may also use type TrackingCallbackWithUser if your tracking library requires user context.
const trackingCallback: TrackingCallback = (experiment, result) => {
  console.log('Viewed Experiment (client-side tracking)', {
    experimentId: experiment.key,
    variationId: result.key,
  });
}

// Create a client-side JS SDK to replay the experiments:
// If using TrackingCallbackWithUser, pass the tracking callback into GrowthBookClient constructor instead of evalFeature.
const growthbook = new GrowthBookClient();

// Dedupe tracked experiments (evalFeature automatically mutates this):
const trackedExperiments = new Set<string>()

export function GrowthbookTrackingClient({
  featureIds,
  attributes,
  payload,
  stickyBucketAssignmentDocs,
}: {
  featureIds: string[];
  attributes: Attributes;
  payload: FeatureApiResponse;
  stickyBucketAssignmentDocs?: Record<string, StickyAssignmentsDocument>;
}) {
  useEffect(() => {
    growthbook.initSync({ payload });
    // saveStickyBucketAssignmentDoc is a no-op because SBs are persisted server-side
    featureIds.forEach((fid) => {
      const ctx: UserContext = {
        attributes,
        stickyBucketAssignmentDocs,
        saveStickyBucketAssignmentDoc: async (doc: StickyAssignmentsDocument) => {},
        trackingCallback,
        trackedExperiments,
      }
      growthbook.evalFeature(fid, ctx);
    })
  }, []);

  return null;
}

3. Implement tracking using <GrowthbookTrackingClient> ex: app/layout.tsx

// ...
import { myFlag, myExperimentFlag } from '@/flags';
import { GrowthbookTracking } from '@/components/growthbook/client-side-tracking/growthbook-tracking.tsx';

export default function Layout() {
  // reference the underlying ids for evaluated flags
  const featureIds = ["my_flag", "my_experiment_flag"];

  return (
    <html>
      <body>
        <div>
          <PageComponent flag={myFlag} />
          <PageComponent2 flag={myExperimentFlag} />
        </div>
        <GrowthbookTracking featureIds={featureIds} />
      </body>
    </html>
  );
}

Follow the example implementation here .

Examples

• Next.js 15+ example using app router

Supported Features

FeaturesAll versions

ExperimentationAll versions

Saved Group References≥ v0.1.0

URL Redirects≥ v0.1.0

Prerequisites≥ v0.1.0

Sticky Bucketing≥ v0.1.0

SemVer Targeting≥ v0.1.0

v2 Hashing≥ v0.1.0

Encrypted Features≥ v0.1.0