Flags Sdk

Flags SDK

The Flags SDK (flags npm package) is a feature flags toolkit for Next.js and SvelteKit. It turns each feature flag into a callable function, works with any flag provider via adapters, and keeps pages static using the precompute pattern. Vercel Flags is the first-party provider, letting you manage flags from the Vercel dashboard or the vercel flags CLI.

• Docs: https://flags-sdk.dev
• Repo: https://github.com/vercel/flags

Core concepts

Flags as code

Each flag is declared as a function. No string keys at call sites:

import { flag } from 'flags/next';

export const exampleFlag = flag({
  key: 'example-flag',
  decide() { return false; },
});

const value = await exampleFlag();

Server-side evaluation

Flags evaluate server-side to avoid layout shift, keep pages static, and maintain confidentiality. Combine routing middleware with the precompute pattern to serve static variants from CDN.

Adapter pattern

Adapters replace decide and origin on a flag declaration, connecting your flags to a provider. Vercel Flags (@flags-sdk/vercel) is the first-party adapter. Third-party adapters are available for Statsig, LaunchDarkly, PostHog, and others.

import { flag } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';

export const exampleFlag = flag({
  key: 'example-flag',
  adapter: vercelAdapter(),
});

Agent workflow: Creating a new flag

When a user asks you to create or add a feature flag, follow these steps in order. Do not leave CLI steps as "next steps" for the user — execute them yourself.

Before you start

Check the project state to adapt commands and decide which steps you can skip:

• Which lockfile is present (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb)? → Adapt all package manager commands accordingly (pnpm add, npm install, yarn add, bun add).
• Is flags in package.json? → Skip install (step 1)
• Does .vercel/ directory exist? → Project is linked, skip vercel link in step 2
• Does .env.local contain FLAGS=? → Env vars already pulled, skip step 3
• Does flags.ts (or lib/flags.ts, src/flags.ts) exist? → Add to it rather than creating from scratch (step 4)
• Is @vercel/toolbar in package.json? → Skip toolbar setup (step 6)
• Does app/.well-known/vercel/flags/route.ts exist? → Flags Explorer already set up, skip step 7

Steps

1. Install packages (if not already in package.json):

   pnpm i flags @flags-sdk/vercel

2. Register the flag with Vercel: Run vercel flags add <flag-key> --kind boolean --description "<description>".

Prerequisite: The vercel flags commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, run pnpm i -g vercel. For authentication or linking issues, read and follow the vercel-cli skill. If it's not installed, run npx skills add https://github.com/vercel/vercel --skill vercel-cli.

Before running vercel flags add, verify the project is linked to Vercel. Check for a .vercel directory in the project root. If it doesn't exist, run vercel link first.

3. Pull environment variables: Run vercel env pull to write FLAGS and FLAGS_SECRET to .env.local. Without these environment variables, vercelAdapter() will not be able to evaluate flags. This step is mandatory after creating a flag.

4. Declare the flag in code: Add it to flags.ts (or create the file if it doesn't exist) using vercelAdapter():

   import { flag } from 'flags/next';
   import { vercelAdapter } from '@flags-sdk/vercel';

   export const myFlag = flag({
     key: 'my-flag',
     adapter: vercelAdapter(),
   });

5. Use the flag: Call it in your page or component and conditionally render based on the result:

   import { myFlag } from '../flags';

   export default async function Page() {
     const enabled = await myFlag();
     return <div>{enabled ? 'Feature on' : 'Feature off'}</div>;
   }

6. Set up the Vercel Toolbar (if not already present):

• Run pnpm i @vercel/toolbar
• Wrap next.config.ts with the toolbar plugin
• Render <VercelToolbar /> in the root layout

See references/nextjs.md — Toolbar Setup for the full code.

7. Set up Flags Explorer (if not already present): Create app/.well-known/vercel/flags/route.ts — see the Flags Explorer setup section below.

Vercel Flags

Vercel Flags is Vercel's feature flags platform. You create and manage flags from the Vercel dashboard or the vercel flags CLI, then connect them to your code with the @flags-sdk/vercel adapter. When you create a flag in Vercel, the FLAGS and FLAGS_SECRET environment variables are configured automatically.

To create a flag end-to-end, follow the Agent workflow above.

For the full Vercel provider reference — user targeting, vercel flags CLI subcommands, custom adapter configuration, and Flags Explorer setup — see references/providers.md.

Declaring flags

When using Vercel Flags, declare flags with vercelAdapter() as shown in the Agent workflow. For other providers, see references/providers.md. Below are the general flag() patterns.

Basic flag

import { flag } from 'flags/next'; // or 'flags/sveltekit'

export const showBanner = flag<boolean>({
  key: 'show-banner',
  description: 'Show promotional banner',
  defaultValue: false,
  options: [
    { value: false, label: 'Hide' },
    { value: true, label: 'Show' },
  ],
  decide() { return false; },
});

Flag with evaluation context

Use identify to establish who the request is for. The returned entities are passed to decide:

import { dedupe, flag } from 'flags/next';
import type { ReadonlyRequestCookies } from 'flags';

interface Entities {
  user?: { id: string };
}

const identify = dedupe(
  ({ cookies }: { cookies: ReadonlyRequestCookies }): Entities => {
    const userId = cookies.get('user-id')?.value;
    return { user: userId ? { id: userId } : undefined };
  },
);

export const dashboardFlag = flag<boolean, Entities>({
  key: 'new-dashboard',
  identify,
  decide({ entities }) {
    if (!entities?.user) return false;
    return ['user1', 'user2'].includes(entities.user.id);
  },
});

Flag with another adapter

Adapters connect flags to third-party providers. Each adapter replaces decide and origin:

import { flag } from 'flags/next';
import { statsigAdapter } from '@flags-sdk/statsig';

export const myGate = flag({
  key: 'my_gate',
  adapter: statsigAdapter.featureGate((gate) => gate.value),
  identify,
});

See references/providers.md for all supported adapters.

Key parameters

Dedupe

Wrap shared functions (especially identify) in dedupe to run them once per request:

import { dedupe } from 'flags/next';

const identify = dedupe(({ cookies }) => {
  return { user: { id: cookies.get('uid')?.value } };
});

Note: dedupe is not available in Pages Router.

Flags Explorer setup

Next.js (App Router)

// app/.well-known/vercel/flags/route.ts
import { createFlagsDiscoveryEndpoint } from 'flags/next';
import { getProviderData } from '@flags-sdk/vercel';
import * as flags from '../../../../flags';

export const GET = createFlagsDiscoveryEndpoint(async () => {
  return getProviderData(flags);
});

With external provider data

When using a third-party provider alongside Vercel Flags, combine their data with mergeProviderData. Each provider adapter exports its own getProviderData — see the provider-specific examples in references/providers.md.

SvelteKit

// src/hooks.server.ts
import { createHandle } from 'flags/sveltekit';
import { FLAGS_SECRET } from '$env/static/private';
import * as flags from '$lib/flags';

export const handle = createHandle({ secret: FLAGS_SECRET, flags });

FLAGS_SECRET

Required for precompute and Flags Explorer. Must be 32 random bytes, base64-encoded:

node -e "console.log(crypto.randomBytes(32).toString('base64url'))"

Use a separate FLAGS_SECRET value for each environment (Development, Preview, Production), and mark the Preview and Production values as Sensitive. Run the generator once per environment to produce distinct values, then store each on Vercel:

vercel env add FLAGS_SECRET production --sensitive --value <production-secret>
vercel env add FLAGS_SECRET preview --sensitive --value <preview-secret>
vercel env add FLAGS_SECRET development --value <development-secret>

Then run vc env pull to sync to local.

Precompute pattern

Use precompute to keep pages static while using feature flags. Middleware evaluates flags and encodes results into the URL via rewrite. The page reads precomputed values instead of re-evaluating.

High-level flow: 1. Declare flags and group them in an array 2. Call precompute(flagGroup) in middleware, get a code string 3. Rewrite request to /${code}/original-path 4. Page reads flag values from code: await myFlag(code, flagGroup)

For full implementation details, see framework-specific references:

• Next.js: See references/nextjs.md — covers proxy middleware, precompute setup, ISR, generatePermutations, multiple groups
• SvelteKit: See references/sveltekit.md — covers reroute hook, middleware, precompute setup, ISR, prerendering

Custom adapters

Create an adapter factory that returns an object with origin and decide. For the full pattern (including default adapter and singleton client examples), see references/providers.md.

Encryption functions

For keeping flag data confidential in the browser (used by Flags Explorer):

All use FLAGS_SECRET by default. Example:

import { encryptFlagValues } from 'flags';
import { FlagValues } from 'flags/react';

async function ConfidentialFlags({ values }) {
  const encrypted = await encryptFlagValues(values);
  return <FlagValues values={encrypted} />;
}

React components

import { FlagValues, FlagDefinitions } from 'flags/react';

// Renders script tag with flag values for Flags Explorer
<FlagValues values={{ myFlag: true }} />

// Renders script tag with flag definitions for Flags Explorer
<FlagDefinitions definitions={{ myFlag: { options: [...], description: '...' } }} />

References

Detailed framework and provider guides are in separate files to keep context lean:

• [references/nextjs.md](references/nextjs.md): Next.js quickstart, toolbar, App Router, Pages Router, middleware/proxy, precompute, dedupe, dashboard pages, marketing pages, suspense fallbacks
• [references/sveltekit.md](references/sveltekit.md): SvelteKit quickstart, toolbar, hooks setup, precompute with reroute + middleware, dashboard pages, marketing pages
• [references/providers.md](references/providers.md): All provider adapters — Vercel, Edge Config, Statsig, LaunchDarkly, PostHog, GrowthBook, Hypertune, Flagsmith, Reflag, Split, Optimizely, OpenFeature, and custom adapters
• [references/api.md](references/api.md): Full API reference for flags, flags/react, flags/next, and flags/sveltekit

API Reference

Table of Contents

• flags (core)
• flags/react
• flags/next
• flags/sveltekit

---

flags (core)

verifyAccess

Verify access to the flags discovery endpoint. Returns Promise<boolean>.

import { verifyAccess } from 'flags';

const access = await verifyAccess(request.headers.get('Authorization'));
if (!access) return NextResponse.json(null, { status: 401 });

mergeProviderData

Merge provider data from multiple sources for the Flags Explorer.

import { mergeProviderData } from 'flags';

return mergeProviderData([
  getProviderData(flags),
  getStatsigProviderData({ /* ... */ }),
]);

reportValue

Report flag value to Vercel for Runtime Logs and Web Analytics.

import { reportValue } from 'flags';
reportValue('summer-sale', true);

Encryption Functions

All default to process.env.FLAGS_SECRET.

Optional secret and expirationTime (default '1y') params on encrypt functions.

verifyAccessProof

Verify an access proof token. Returns Promise<boolean>.

safeJsonStringify

XSS-safe JSON.stringify. Escapes < and other dangerous chars.

import { safeJsonStringify } from 'flags';
safeJsonStringify({ markup: '<html></html>' });
// '{"markup":"\\u003chtml>\\u003c/html>"}'

---

flags/react

FlagValues

Renders a <script data-flag-values> tag for the Flags Explorer.

import { FlagValues } from 'flags/react';
<FlagValues values={{ myFlag: true }} />

For confidential flags, encrypt first:

import { encryptFlagValues } from 'flags';
import { FlagValues } from 'flags/react';

async function ConfidentialFlags({ values }) {
  const encrypted = await encryptFlagValues(values);
  return <FlagValues values={encrypted} />;
}

FlagDefinitions

Renders a <script data-flag-definitions> tag with flag metadata.

import { FlagDefinitions } from 'flags/react';

<FlagDefinitions definitions={{
  myFlag: {
    options: [{ value: false }, { value: true }],
    origin: 'https://example.com/flag/myFlag',
    description: 'Example flag',
  },
}} />

---

flags/next

flag

Declare a feature flag for Next.js.

createFlagsDiscoveryEndpoint

Creates an App Router route handler for /.well-known/vercel/flags. Auto-verifies access and adds version header.

getProviderData

Turn flag() declarations into Flags Explorer-compatible definitions.

precompute

Evaluate multiple flags, return encoded string.

evaluate

Evaluate multiple flags, return their values as array.

serialize

Turn evaluated flags into serialized representation.

getPrecomputed

Retrieve flag values from precomputation code.

deserialize

Retrieve all flag values as a record from code.

generatePermutations

Generate all possible precomputation codes for flag options.

dedupe

Deduplicate function calls per request.

Not available in Pages Router.

---

flags/sveltekit

flag

Declare a feature flag for SvelteKit.

createHandle

Server hook that establishes context for flags and handles /.well-known/vercel/flags.

Must come first when composed with sequence.

getProviderData

Turn flag declarations into Flags Explorer-compatible definitions.

precompute

Evaluate multiple flags, return encoded string.

generatePermutations

Generate all precomputation codes for prerendering.

Next.js Integration

Table of Contents

• Quickstart
• Toolbar Setup
• App Router
• Pages Router
• Evaluation Context
• Dedupe
• Precompute
• Dashboard Pages
• Marketing Pages
• Proxy (Middleware)
• Suspense Fallbacks

Quickstart

pnpm i flags

Declare a flag in flags.ts:

import { flag } from 'flags/next';

export const exampleFlag = flag({
  key: 'example-flag',
  decide() {
    return Math.random() > 0.5;
  },
});

Toolbar Setup

1. Install @vercel/toolbar:

pnpm i @vercel/toolbar

2. Add Next.js plugin:

// next.config.ts
import type { NextConfig } from 'next';
import createWithVercelToolbar from '@vercel/toolbar/plugins/next';

const nextConfig: NextConfig = {};

const withVercelToolbar = createWithVercelToolbar();
export default withVercelToolbar(nextConfig);

3. Render toolbar in root layout:

// app/layout.tsx
import { VercelToolbar } from '@vercel/toolbar/next';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  // On Vercel, the toolbar is auto-injected in preview deployments.
  // This manual injection is only needed for local development.
  const shouldInjectToolbar = process.env.NODE_ENV === 'development';
  return (
    <html lang="en">
      <body>
        {children}
        {shouldInjectToolbar && <VercelToolbar />}
      </body>
    </html>
  );
}

App Router

Call the flag function from any async server component or proxy:

// app/page.tsx
import { exampleFlag } from '../flags';

export default async function Page() {
  const example = await exampleFlag();
  return <div>{example ? 'Flag is on' : 'Flag is off'}</div>;
}

Pages Router

Pass req to the flag in getServerSideProps:

// pages/index.tsx
import type { InferGetServerSidePropsType, GetServerSideProps } from 'next';
import { exampleFlag } from '../flags';

export const getServerSideProps = (async ({ req }) => {
  const example = await exampleFlag(req);
  return { props: { example } };
}) satisfies GetServerSideProps<{ example: boolean }>;

export default function Page({
  example,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
  return <div>{example ? 'Flag is on' : 'Flag is off'}</div>;
}

Evaluation Context

Use identify to establish who the request is for. The returned entities are passed to decide:

import { flag, dedupe } from 'flags/next';
import type { ReadonlyRequestCookies } from 'flags';

interface Entities {
  user?: { id: string };
}

const identify = dedupe(
  ({ cookies }: { cookies: ReadonlyRequestCookies }): Entities => {
    const userId = cookies.get('user-id')?.value;
    return { user: userId ? { id: userId } : undefined };
  },
);

export const myFlag = flag<boolean, Entities>({
  key: 'my-flag',
  identify,
  decide({ entities }) {
    return entities?.user?.id === 'user1';
  },
});

identify receives normalized headers and cookies that work across App Router, Pages Router, and Proxy.

Custom evaluation context

Override identify at call site (use sparingly):

await exampleFlag.run({ identify: { user: { id: 'user1' } } });
await exampleFlag.run({ identify: () => ({ user: { id: 'user1' } }) });

Dedupe

Wrap functions in dedupe to run them once per request within the same runtime:

import { dedupe } from 'flags/next';

const identify = dedupe(({ cookies }) => {
  return { user: { id: cookies.get('uid')?.value } };
});

Use cases:

• Prevent duplicate identify calls across multiple flags
• Generate consistent random IDs for anonymous visitor experiments

Not available in Pages Router.

Precompute

Keep pages static while using feature flags. Proxy evaluates flags and encodes results into the URL.

Prerequisites

Set FLAGS_SECRET env var (32 random bytes, base64-encoded). Use a separate value for each environment (Development, Preview, Production), and mark the Preview and Production values as Sensitive. Run the generator once per environment to produce distinct values:

node -e "console.log(crypto.randomBytes(32).toString('base64url'))"

Store each on Vercel:

vercel env add FLAGS_SECRET production --sensitive --value <production-secret>
vercel env add FLAGS_SECRET preview --sensitive --value <preview-secret>
vercel env add FLAGS_SECRET development --value <development-secret>

Step 1: Create flag group

// flags.ts
import { flag } from 'flags/next';

export const showSummerSale = flag({
  key: 'summer-sale',
  decide: () => false,
});

export const showBanner = flag({
  key: 'banner',
  decide: () => false,
});

export const marketingFlags = [showSummerSale, showBanner] as const;

Step 2: Precompute in proxy

// proxy.ts
import { type NextRequest, NextResponse } from 'next/server';
import { precompute } from 'flags/next';
import { marketingFlags } from './flags';

export const config = { matcher: ['/'] };

export async function proxy(request: NextRequest) {
  const code = await precompute(marketingFlags);
  const nextUrl = new URL(
    `/${code}${request.nextUrl.pathname}${request.nextUrl.search}`,
    request.url,
  );
  return NextResponse.rewrite(nextUrl, { request });
}

Step 3: Read precomputed values in page

// app/[code]/page.tsx
import { marketingFlags, showSummerSale, showBanner } from '../../flags';

type Params = Promise<{ code: string }>;

export default async function Page({ params }: { params: Params }) {
  const { code } = await params;
  const summerSale = await showSummerSale(code, marketingFlags);
  const banner = await showBanner(code, marketingFlags);

  return (
    <div>
      {banner && <p>welcome</p>}
      {summerSale ? <p>summer sale live</p> : <p>summer sale soon</p>}
    </div>
  );
}

Step 4: Enable ISR & build time prerendering

// app/[code]/layout.tsx
import { generatePermutations } from 'flags/next';

export async function generateStaticParams() {
  const codes = await generatePermutations(marketingFlags);
  return codes.map((code) => ({ code }));
}

export default async function Layout({ children }) {
  return children;
}

Declaring options

Options enable efficient URL encoding and Flags Explorer display:

export const greetingFlag = flag<string>({
  key: 'greeting',
  options: ['Hello world', 'Hi', 'Hola'],
  decide: () => 'Hello world',
});

Or with labels:

export const greetingFlag = flag<string>({
  key: 'greeting',
  options: [
    { label: 'Hello world', value: 'Hello world' },
    { label: 'Hi', value: 'Hi' },
  ],
  decide: () => 'Hello world',
});

Multiple groups

Avoid unnecessary permutations by creating separate flag groups per page:

export const rootFlags = [navigationFlag, bannerFlag];
export const pricingFlags = [discountFlag];

File tree:

app/[rootCode]/
  page.tsx
  pricing/[pricingCode]/
    page.tsx

Pages Router precompute

// pages/[code]/index.tsx
import { generatePermutations } from 'flags/next';

export const getStaticPaths = (async () => {
  const codes = await generatePermutations(marketingFlags);
  return {
    paths: codes.map((code) => ({ params: { code } })),
    fallback: 'blocking',
  };
}) satisfies GetStaticPaths;

export const getStaticProps = (async (context) => {
  if (typeof context.params?.code !== 'string') return { notFound: true };
  const example = await exampleFlag(context.params.code, marketingFlags);
  return { props: { example } };
}) satisfies GetStaticProps<{ example: boolean }>;

Dashboard Pages

For authenticated dashboard pages, use identify to read user context from cookies/JWTs:

import type { ReadonlyRequestCookies } from 'flags';
import { flag, dedupe } from 'flags/next';

interface Entities {
  user?: { id: string };
}

const identify = dedupe(
  ({ cookies }: { cookies: ReadonlyRequestCookies }): Entities => {
    const userId = cookies.get('dashboard-user-id')?.value;
    return { user: userId ? { id: userId } : undefined };
  },
);

export const dashboardFlag = flag<boolean, Entities>({
  key: 'dashboard-flag',
  identify,
  decide({ entities }) {
    if (!entities?.user) return false;
    const allowedUsers = ['user1'];
    return allowedUsers.includes(entities.user.id);
  },
});

Usage in a page:

export default async function DashboardPage() {
  const dashboard = await dashboardFlag();
  return <div>{dashboard ? 'New Dashboard' : 'Old Dashboard'}</div>;
}

Marketing Pages

For static marketing pages with A/B tests, combine precompute with visitor ID generation:

Visitor ID in proxy

// proxy.ts
import { precompute } from 'flags/next';
import { type NextRequest, NextResponse } from 'next/server';
import { marketingFlags } from './flags';
import { getOrGenerateVisitorId } from './get-or-generate-visitor-id';

export async function marketingProxy(request: NextRequest) {
  const visitorId = await getOrGenerateVisitorId(
    request.cookies,
    request.headers,
  );

  const code = await precompute(marketingFlags);

  return NextResponse.rewrite(
    new URL(`/examples/marketing-pages/${code}`, request.url),
    {
      headers: {
        'Set-Cookie': `marketing-visitor-id=${visitorId}; Path=/`,
        'x-marketing-visitor-id': visitorId,
      },
    },
  );
}

Deduplicated visitor ID generation

import { nanoid } from 'nanoid';
import { dedupe } from 'flags/next';
import type { ReadonlyHeaders, ReadonlyRequestCookies } from 'flags';

const generateId = dedupe(async () => nanoid());

export const getOrGenerateVisitorId = async (
  cookies: ReadonlyRequestCookies,
  headers: ReadonlyHeaders,
) => {
  const cookieVisitorId = cookies.get('marketing-visitor-id')?.value;
  if (cookieVisitorId) return cookieVisitorId;

  const headerVisitorId = headers.get('x-marketing-visitor-id');
  if (headerVisitorId) return headerVisitorId;

  return generateId();
};

Flag using visitor ID

const identify = dedupe(
  async ({ cookies }: { cookies: ReadonlyRequestCookies }): Promise<Entities> => {
    const visitorId = await getOrGenerateVisitorId(cookies);
    return { visitor: visitorId ? { id: visitorId } : undefined };
  },
);

export const marketingAbTest = flag<boolean, Entities>({
  key: 'marketing-ab-test-flag',
  identify,
  decide({ entities }) {
    if (!entities?.visitor) return false;
    return /^[a-n0-5]/i.test(entities.visitor.id);
  },
});

Proxy (Middleware)

Use flags in proxy to rewrite requests to static page variants:

// proxy.ts
import { type NextRequest, NextResponse } from 'next/server';
import { myFlag } from './flags';

export const config = { matcher: ['/example'] };

export async function proxy(request: NextRequest) {
  const active = await myFlag();
  const variant = active ? 'variant-on' : 'variant-off';
  return NextResponse.rewrite(new URL(`/example/${variant}`, request.url));
}

For multiple flags on one page, use the precompute pattern instead.

Suspense Fallbacks

Combine precomputed flags with Partial Prerendering to serve matching skeletons:

async function Example() {
  const hasAuth = await hasAuthCookieFlag();

  return (
    <Suspense fallback={hasAuth ? <AuthedSkeleton /> : <UnauthedSkeleton />}>
      <Dashboard />
    </Suspense>
  );
}

The hasAuthCookieFlag checks cookie existence without authenticating. Two shells get prerendered — one for each auth state — served statically with no layout shift.

Flags Explorer (Next.js)

The Flags Explorer is part of the Vercel Toolbar. Before adding the discovery endpoint below, make sure the toolbar is set up by following the Toolbar Setup steps first.

App Router

// app/.well-known/vercel/flags/route.ts
import { getProviderData, createFlagsDiscoveryEndpoint } from 'flags/next';
import * as flags from '../../../../flags';

export const GET = createFlagsDiscoveryEndpoint(async () => {
  return getProviderData(flags);
});

Pages Router

Requires a rewrite in next.config.js:

module.exports = {
  async rewrites() {
    return [
      {
        source: '/.well-known/vercel/flags',
        destination: '/api/vercel/flags',
      },
    ];
  },
};

// pages/api/vercel/flags.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { verifyAccess } from 'flags';

export async function handler(req: NextApiRequest, res: NextApiResponse) {
  const access = await verifyAccess(req.headers.authorization);
  if (!access) return res.status(401).json(null);

  const providerData = { /* ... */ };
  return res.status(200).json(providerData);
}

Provider Adapters

Table of Contents

• Vercel
• Edge Config
• Statsig
• LaunchDarkly
• PostHog
• GrowthBook
• Hypertune
• Flagsmith
• Reflag
• OpenFeature
• Split
• Optimizely
• Custom Adapters

---

Vercel

Package: @flags-sdk/vercel

pnpm i flags @flags-sdk/vercel

Setup

Prerequisite: The vercel flags commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, run pnpm i -g vercel. For authentication or linking issues, read and follow the vercel-cli skill. If it's not installed, run npx skills add https://github.com/vercel/vercel --skill vercel-cli.

Before running any vercel flags command, verify the project is linked to Vercel. Check for a .vercel directory in the project root. If it doesn't exist, run vercel link first.

1. Create a flag in the Vercel dashboard or via CLI: vercel flags add <flag-key> --kind boolean --description "<description>" 2. Pull env vars: you must run vercel env pull to write FLAGS and FLAGS_SECRET to .env.local. Without these environment variables, vercelAdapter() will not be able to evaluate flags. 3. Declare the flag:

import { flag } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';

export const exampleFlag = flag({
  key: 'example-flag',
  adapter: vercelAdapter(),
});

User targeting

import { dedupe, flag } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';

type Entities = {
  team?: { id: string };
  user?: { id: string };
};

const identify = dedupe(async (): Promise<Entities> => ({
  team: { id: 'team-123' },
  user: { id: 'user-456' },
}));

export const exampleFlag = flag<boolean, Entities>({
  key: 'example-flag',
  identify,
  adapter: vercelAdapter(),
});

Flags Explorer

import { createFlagsDiscoveryEndpoint } from 'flags/next';
import { getProviderData } from '@flags-sdk/vercel';
import * as flags from '../../../../flags';

export const GET = createFlagsDiscoveryEndpoint(async () => {
  return await getProviderData(flags);
});

Custom configuration

import { createVercelAdapter } from '@flags-sdk/vercel';

const customAdapter = createVercelAdapter(process.env.CUSTOM_FLAGS_KEY!);

export const exampleFlag = flag({
  key: 'example-flag',
  adapter: customAdapter(),
});

Using your own client (e.g. for singleton)

If the app also uses @vercel/flags-core directly, create the client once and pass it to the adapter so both share the same instance:

import { createClient } from '@vercel/flags-core';
import { createVercelAdapter } from '@flags-sdk/vercel';

const vercelFlagsClient = createClient(process.env.FLAGS);
const vercelAdapter = createVercelAdapter(vercelFlagsClient);

export const exampleFlag = flag({
  key: 'example-flag',
  adapter: vercelAdapter(),
});

vercel flags CLI

Manage Vercel Flags from the terminal. Requires the Vercel CLI and a linked project.

Prerequisite: The Vercel CLI must be installed (pnpm i -g vercel) and the project must be linked (vercel link — check for a .vercel directory). For authentication issues, read and follow the vercel-cli skill.

Subcommands

Create and toggle a flag

# Create a boolean flag with a description
vercel flags add my-feature --kind boolean --description "New onboarding flow"

# Enable in development first
vercel flags enable my-feature --environment development

# Promote to production
vercel flags enable my-feature --environment production

# Disable in production
vercel flags disable my-feature --environment production

# Change string variant in production
vercel flags set my-feature -e production --variant my-variant

enable and disable only work with boolean flags. For changing the state of other flag types, use the set command. Use the vercel-cli skill for full reference.

Inspect and list flags

# Show details of a specific flag (status, environments, targeting rules)
vercel flags inspect my-feature

# List all flags in the project
vercel flags list

Archive and delete a flag

A flag must be archived before it can be deleted:

vercel flags archive my-feature
vercel flags rm my-feature

Manage SDK keys

SDK keys connect your application to Vercel Flags. The FLAGS environment variable contains an SDK key.

# List SDK keys for the project
vercel flags sdk-keys ls

# Create a new SDK key
vercel flags sdk-keys add

# Remove an SDK key
vercel flags sdk-keys rm <sdk-key-id>

These examples cover common flag operations. For the full vercel flags reference and other Vercel CLI commands, see the vercel-cli skill. If it's not installed: npx skills add https://github.com/vercel/vercel --skill vercel-cli

Full CLI reference: https://vercel.com/docs/cli/flags

---

Edge Config

Package: @flags-sdk/edge-config

pnpm i @flags-sdk/edge-config

Env: EDGE_CONFIG="edge-config-connection-string"

Usage

import { flag } from 'flags/next';
import { edgeConfigAdapter } from '@flags-sdk/edge-config';

export const exampleFlag = flag({
  adapter: edgeConfigAdapter(),
  key: 'example-flag',
});

Edge Config should contain:

{
  "flags": {
    "example-flag": true,
    "another-flag": false
  }
}

Custom configuration

import { createEdgeConfigAdapter } from '@flags-sdk/edge-config';

const myAdapter = createEdgeConfigAdapter({
  connectionString: process.env.OTHER_EDGE_CONFIG,
  options: {
    edgeConfigItemKey: 'other-flags-key',
    teamSlug: 'my-team',
  },
});

---

Statsig

Package: @flags-sdk/statsig

pnpm i @flags-sdk/statsig

Env vars:

• STATSIG_SERVER_API_KEY (required)
• STATSIG_PROJECT_ID (optional)
• EXPERIMENTATION_CONFIG (optional, Edge Config)
• EXPERIMENTATION_CONFIG_ITEM_KEY (optional)

Methods

import { statsigAdapter, type StatsigUser } from '@flags-sdk/statsig';

// Feature Gates
export const myGate = flag<boolean, StatsigUser>({
  key: 'my_feature_gate',
  adapter: statsigAdapter.featureGate((gate) => gate.value),
  identify,
});

// Dynamic Configs
export const myConfig = flag<Record<string, unknown>, StatsigUser>({
  key: 'my_dynamic_config',
  adapter: statsigAdapter.dynamicConfig((config) => config.value),
  identify,
});

// Experiments
export const myExperiment = flag<Record<string, unknown>, StatsigUser>({
  key: 'my_experiment',
  adapter: statsigAdapter.experiment((config) => config.value),
  identify,
});

// Autotune
export const myAutotune = flag<Record<string, unknown>, StatsigUser>({
  key: 'my_autotune',
  adapter: statsigAdapter.autotune((config) => config.value),
  identify,
});

// Layers
export const myLayer = flag<Record<string, unknown>, StatsigUser>({
  key: 'my_layer',
  adapter: statsigAdapter.layer((layer) => layer.value),
  identify,
});

Same key, different mappings

Use . to distinguish flags from the same config:

export const text = flag<string, StatsigUser>({
  key: 'my_config.text',
  adapter: statsigAdapter.dynamicConfig((c) => c.value.text as string),
  identify,
});

export const price = flag<number, StatsigUser>({
  key: 'my_config.price',
  adapter: statsigAdapter.dynamicConfig((c) => c.value.price as number),
  identify,
});

Exposure logging

Disabled by default (middleware prefetch would cause premature exposures). Enable explicitly:

adapter: statsigAdapter.featureGate((gate) => gate.value, {
  exposureLogging: true,
})

Log exposures from the client instead when possible.

Flags Explorer

import { getProviderData as getStatsigProviderData } from '@flags-sdk/statsig';
import { mergeProviderData } from 'flags';

export const GET = createFlagsDiscoveryEndpoint(async () => {
  return mergeProviderData([
    getProviderData(flags),
    getStatsigProviderData({
      consoleApiKey: process.env.STATSIG_CONSOLE_API_KEY,
      projectId: process.env.STATSIG_PROJECT_ID,
    }),
  ]);
});

---

LaunchDarkly

Package: @flags-sdk/launchdarkly

pnpm i @flags-sdk/launchdarkly

Env vars:

• LAUNCHDARKLY_CLIENT_SIDE_ID (required)
• LAUNCHDARKLY_PROJECT_SLUG (required)
• EDGE_CONFIG (required)

Usage

import { ldAdapter, type LDContext } from '@flags-sdk/launchdarkly';

const identify = dedupe((async ({ headers, cookies }) => {
  const user = await getUser(headers, cookies);
  return { key: user.userID };
}) satisfies Identify<LDContext>);

export const exampleFlag = flag<boolean, LDContext>({
  key: 'example-flag',
  identify,
  adapter: ldAdapter.variation(),
});

Flags Explorer

import { getProviderData as getLDProviderData } from '@flags-sdk/launchdarkly';

return mergeProviderData([
  getProviderData(flags),
  getLDProviderData({
    apiKey: process.env.LAUNCHDARKLY_API_KEY,
    projectKey: process.env.LAUNCHDARKLY_PROJECT_KEY,
    environment: process.env.LAUNCHDARKLY_ENVIRONMENT,
  }),
]);

---

PostHog

Package: @flags-sdk/posthog

pnpm i @flags-sdk/posthog

Env vars:

• NEXT_PUBLIC_POSTHOG_KEY
• NEXT_PUBLIC_POSTHOG_HOST (e.g. https://us.i.posthog.com)

Methods

import { postHogAdapter } from '@flags-sdk/posthog';

// Boolean check
export const myFlag = flag({
  key: 'my-flag',
  adapter: postHogAdapter.isFeatureEnabled(),
  identify,
});

// Multivariate value
export const myVariant = flag({
  key: 'my-flag',
  adapter: postHogAdapter.featureFlagValue(),
  identify,
});

// Payload
export const myPayload = flag({
  key: 'my-flag',
  adapter: postHogAdapter.featureFlagPayload((v) => v),
  defaultValue: {},
  identify,
});

Flags Explorer

Requires: POSTHOG_PERSONAL_API_KEY, POSTHOG_PROJECT_ID

import { getProviderData as getPostHogProviderData } from '@flags-sdk/posthog';

export const GET = createFlagsDiscoveryEndpoint(() =>
  getPostHogProviderData({
    personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY,
    projectId: process.env.NEXT_PUBLIC_POSTHOG_PROJECT_ID,
  }),
);

---

GrowthBook

Package: @flags-sdk/growthbook

pnpm i @flags-sdk/growthbook

Env: GROWTHBOOK_CLIENT_KEY (required)

Usage

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

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

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

Edge Config

Set GROWTHBOOK_EDGE_CONNECTION_STRING or EXPERIMENTATION_CONFIG (Vercel Marketplace).

Tracking

growthbookAdapter.setTrackingCallback((experiment, result) => {
  after(async () => {
    console.log('Experiment', experiment.key, 'Variation', result.key);
  });
});

---

Hypertune

Package: @flags-sdk/hypertune

pnpm i hypertune flags server-only @flags-sdk/hypertune @vercel/edge-config

Requires code generation: npx hypertune

import { createHypertuneAdapter } from '@flags-sdk/hypertune';
import { createSource, flagFallbacks, vercelFlagDefinitions, type Context, type FlagValues } from './generated/hypertune';

const hypertuneAdapter = createHypertuneAdapter<FlagValues, Context>({
  createSource,
  flagFallbacks,
  flagDefinitions: vercelFlagDefinitions,
  identify,
});

export const exampleFlag = flag(hypertuneAdapter.declarations.exampleFlag);

---

Flagsmith

Package: @flags-sdk/flagsmith

pnpm i @flags-sdk/flagsmith

Env: FLAGSMITH_ENVIRONMENT_ID (required)

Usage with type coercion

import { flagsmithAdapter } from '@flags-sdk/flagsmith';

export const buttonColor = flag<string>({
  key: 'button-color',
  defaultValue: 'blue',
  adapter: flagsmithAdapter.getValue({ coerce: 'string' }),
});

export const showBanner = flag<boolean>({
  key: 'show-banner',
  defaultValue: false,
  adapter: flagsmithAdapter.getValue({ coerce: 'boolean' }),
});

Coercion options: 'string', 'number', 'boolean', or omit for raw value.

---

Reflag

Package: @flags-sdk/reflag

pnpm i @flags-sdk/reflag

Env: REFLAG_SECRET_KEY

import { reflagAdapter, type Context } from '@flags-sdk/reflag';

const identify = dedupe((async ({ headers, cookies }) => ({
  user: { id: 'user-id', name: 'name', email: 'email' },
  company: { id: 'company-id' },
})) satisfies Identify<Context>);

export const myFeature = flag<boolean, Context>({
  key: 'my_feature',
  identify,
  adapter: reflagAdapter.isEnabled(),
});

---

OpenFeature

Package: @flags-sdk/openfeature + @openfeature/server-sdk

pnpm i @flags-sdk/openfeature @openfeature/server-sdk

Setup

import { createOpenFeatureAdapter } from '@flags-sdk/openfeature';

// Sync provider
OpenFeature.setProvider(new YourProvider());
const adapter = createOpenFeatureAdapter(OpenFeature.getClient());

// Async provider
const adapter = createOpenFeatureAdapter(async () => {
  await OpenFeature.setProviderAndWait(new YourProvider());
  return OpenFeature.getClient();
});

Methods

adapter.booleanValue()  // boolean flags
adapter.stringValue()   // string flags
adapter.numberValue()   // number flags
adapter.objectValue()   // object flags

All require defaultValue on the flag declaration.

---

Split

Package: @flags-sdk/split (Flags Explorer only, adapter coming soon)

import { getProviderData as getSplitProviderData } from '@flags-sdk/split';

getSplitProviderData({
  adminApiKey: process.env.SPLIT_ADMIN_API_KEY,
  environmentId: process.env.SPLIT_ENVIRONMENT_ID,
  organizationId: process.env.SPLIT_ORG_ID,
  workspaceId: process.env.SPLIT_WORKSPACE_ID,
});

---

Optimizely

Package: @flags-sdk/optimizely (Flags Explorer only, adapter coming soon)

import { getProviderData as getOptimizelyProviderData } from '@flags-sdk/optimizely';

getOptimizelyProviderData({
  projectId: process.env.OPTIMIZELY_PROJECT_ID,
  apiKey: process.env.OPTIMIZELY_API_KEY,
});

---

Custom Adapters

Create an adapter factory:

import type { Adapter } from 'flags';

export function createMyAdapter(/* options */) {
  return function myAdapter<ValueType, EntitiesType>(): Adapter<ValueType, EntitiesType> {
    return {
      origin(key) {
        return `https://my-provider.com/flags/${key}`;
      },
      async decide({ key }): Promise<ValueType> {
        return false as ValueType;
      },
    };
  };
}

Default adapter pattern

Expose a lazily-initialized default for simpler usage:

let defaultAdapter: ReturnType<typeof createMyAdapter> | undefined;

export function myAdapter<V, E>(): Adapter<V, E> {
  if (!defaultAdapter) {
    if (!process.env.MY_API_KEY) throw new Error('Missing MY_API_KEY');
    defaultAdapter = createMyAdapter(process.env.MY_API_KEY);
  }
  return defaultAdapter<V, E>();
}

Usage:

import { myAdapter } from './my-adapter';

export const exampleFlag = flag({
  key: 'example',
  adapter: myAdapter(),
});

SvelteKit Integration

Table of Contents

• Quickstart
• Toolbar Setup
• Flag Declaration
• Evaluation Context
• Precompute
• Dashboard Pages
• Marketing Pages

Quickstart

Installation

pnpm i flags @vercel/toolbar

Create a flag

// src/lib/flags.ts
import { flag } from 'flags/sveltekit';

export const showDashboard = flag<boolean>({
  key: 'showDashboard',
  description: 'Show the dashboard',
  origin: 'https://example.com/#showdashboard',
  options: [{ value: true }, { value: false }],
  decide(_event) {
    return false;
  },
});

Set up the server hook

One-time setup that makes the toolbar aware of your flags:

// src/hooks.server.ts
import { createHandle } from 'flags/sveltekit';
import { FLAGS_SECRET } from '$env/static/private';
import * as flags from '$lib/flags';

export const handle = createHandle({ secret: FLAGS_SECRET, flags });

When composing with other handlers via SvelteKit's sequence, createHandle must come first.

Use the flag

// src/routes/+page.server.ts
import { showDashboard } from '$lib/flags';

export const load = async () => {
  const dashboard = await showDashboard();
  return {
    post: { title: dashboard ? 'New Dashboard' : 'Old Dashboard' },
  };
};

<!-- src/routes/+page.svelte -->
<script lang="ts">
  import type { PageProps } from './$types';
  let { data }: PageProps = $props();
</script>

<h1>{data.post.title}</h1>

Toolbar Setup

1. Install @vercel/toolbar 2. Add vite plugin:

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
import { vercelToolbar } from '@vercel/toolbar/plugins/vite';

export default defineConfig({
  plugins: [sveltekit(), vercelToolbar()],
});

3. Render toolbar in layout:

<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import type { LayoutProps } from './$types';
  import { mountVercelToolbar } from '@vercel/toolbar/vite';
  import { onMount } from 'svelte';

  onMount(() => mountVercelToolbar());

  let { children }: LayoutProps = $props();
</script>

<main>
  {@render children()}
</main>

Flag Declaration

import { flag } from 'flags/sveltekit';

export const showSummerSale = flag<boolean>({
  key: 'summer-sale',
  async decide() { return false; },
  origin: 'https://example.com/flags/summer-sale/',
  description: 'Show Summer Holiday Sale Banner, 20% off',
  options: [
    { value: false, label: 'Hide' },
    { value: true, label: 'Show' },
  ],
});

Evaluation Context

Use identify to segment users. Headers and cookies are normalized:

import { flag } from 'flags/sveltekit';

interface Entities {
  user?: { id: string };
}

export const exampleFlag = flag<boolean, Entities>({
  key: 'identify-example-flag',
  identify({ headers, cookies }) {
    const userId = cookies.get('user-id')?.value;
    return { user: userId ? { id: userId } : undefined };
  },
  decide({ entities }) {
    return entities?.user?.id === 'user1';
  },
});

Deduplication

Extract identify as a named function and reuse across flags. Calls are deduped by function identity:

import type { ReadonlyHeaders, ReadonlyRequestCookies } from 'flags';
import { flag } from 'flags/sveltekit';

interface Entities {
  visitorId?: string;
}

function identify({
  cookies,
  headers,
}: {
  cookies: ReadonlyRequestCookies;
  headers: ReadonlyHeaders;
}): Entities {
  const visitorId =
    cookies.get('visitorId')?.value ?? headers.get('x-visitorId');
  return { visitorId };
}

export const flag1 = flag<boolean, Entities>({
  key: 'flag1',
  identify,
  decide({ entities }) { /* ... */ },
});

export const flag2 = flag<boolean, Entities>({
  key: 'flag2',
  identify,
  decide({ entities }) { /* ... */ },
});

Precompute

Why both Routing Middleware and reroute

• middleware.ts handles full page visits in production (runs before CDN)
• reroute handles client-side navigations and dev-time routing
• Middleware has access to cookies and private env vars; reroute runs on client and must defer to server

Step 1: Create flag group

// src/lib/flags.ts
import { flag } from 'flags/sveltekit';

export const firstPricingABTest = flag({
  key: 'firstPricingABTest',
  decide: () => false,
});

export const secondPricingABTest = flag({
  key: 'secondPricingABTest',
  decide: () => false,
});

// src/lib/precomputed-flags.ts
import { precompute } from 'flags/sveltekit';
import { firstPricingABTest, secondPricingABTest } from './flags';

export const pricingFlags = [firstPricingABTest, secondPricingABTest];

export async function computeInternalRoute(pathname: string, request: Request) {
  if (pathname === '/pricing') {
    return '/pricing/' + (await precompute(pricingFlags, request));
  }
  return pathname;
}

Step 2: Set up reroute hook

// src/hooks.ts
export async function reroute({ url, fetch }) {
  if (url.pathname === '/pricing') {
    const destination = new URL('/api/reroute', url);
    destination.searchParams.set('pathname', url.pathname);
    return fetch(destination).then((response) => response.text());
  }
}

// src/routes/api/reroute/+server.ts
import { text } from '@sveltejs/kit';
import { computeInternalRoute } from '$lib/precomputed-flags';

export async function GET({ url, request }) {
  const destination = await computeInternalRoute(
    url.searchParams.get('pathname')!,
    request,
  );
  return text(destination);
}

Step 3: Set up middleware

// middleware.ts
import { rewrite } from '@vercel/edge';
import { normalizeUrl } from '@sveltejs/kit';
import { computeInternalRoute } from './src/lib/precomputed-flags';

export const config = { matcher: ['/pricing'] };

export default async function middleware(request: Request) {
  const { url, denormalize } = normalizeUrl(request.url);
  if (url.pathname === '/pricing') {
    return rewrite(
      denormalize(await computeInternalRoute(url.pathname, request)),
    );
  }
}

Step 4: Read precomputed values

// src/routes/pricing/[code]/+page.server.ts
import type { PageServerLoad } from './$types';
import { firstPricingABTest, secondPricingABTest } from '$lib/flags';
import { pricingFlags } from '$lib/precomputed-flags';

export const load: PageServerLoad = async ({ params }) => {
  const flag1 = await firstPricingABTest(params.code, pricingFlags);
  const flag2 = await secondPricingABTest(params.code, pricingFlags);
  return {
    first: `First: ${flag1}`,
    second: `Second: ${flag2}`,
  };
};

<!-- src/routes/pricing/[code]/+page.svelte -->
<script>
  let { data } = $props();
</script>

<p>{data.first}</p>
<p>{data.second}</p>

Enable ISR

// src/routes/pricing/[code]/+page.server.ts
export const config = {
  isr: { expiration: false },
};

Enable prerendering

import { generatePermutations } from 'flags/sveltekit';
import { pricingFlags } from '$lib/precomputed-flags';

export const prerender = true;

export async function entries() {
  return (await generatePermutations(pricingFlags)).map((code) => ({ code }));
}

Dashboard Pages

// src/lib/flags.ts
import { flag } from 'flags/sveltekit';

export const showNewDashboard = flag<boolean>({
  key: 'showNewDashboard',
  decide({ cookies }) {
    return cookies.get('showNewDashboard')?.value === 'true';
  },
});

// src/routes/+page.server.ts
import type { PageServerLoad } from './$types';
import { showNewDashboard } from '$lib/flags';

export const load: PageServerLoad = async () => {
  const dashboard = await showNewDashboard();
  return { title: dashboard ? 'New Dashboard' : 'Old Dashboard' };
};

Marketing Pages

Combine precompute with visitor ID generation for A/B tests on static pages:

Middleware with visitor ID

// middleware.ts
import { rewrite } from '@vercel/edge';
import { parse } from 'cookie';
import { normalizeUrl } from '@sveltejs/kit';
import { computeInternalRoute, createVisitorId } from './src/lib/precomputed-flags';

export const config = { matcher: ['/examples/marketing-pages'] };

export default async function middleware(request: Request) {
  const { url, denormalize } = normalizeUrl(request.url);

  let visitorId = parse(request.headers.get('cookie') ?? '').visitorId || '';
  if (!visitorId) {
    visitorId = createVisitorId();
    request.headers.set('x-visitorId', visitorId);
  }

  return rewrite(
    denormalize(await computeInternalRoute(url.pathname, request)),
  );
}

Flags with identify

// src/lib/flags.ts
import { flag } from 'flags/sveltekit';

interface Entities {
  visitorId?: string;
}

function identify({ cookies, headers }) {
  const visitorId =
    cookies.get('visitorId')?.value ?? headers.get('x-visitorId');
  if (!visitorId) throw new Error('Visitor ID not found');
  return { visitorId };
}

export const firstMarketingABTest = flag<boolean, Entities>({
  key: 'firstMarketingABTest',
  identify,
  decide({ entities }) {
    if (!entities?.visitorId) return false;
    return /^[a-n0-5]/i.test(entities.visitorId);
  },
});

The x-visitorId header ensures the visitor ID is available even on the first request before the cookie is set.