Index of every page on this site: llms.txt
All skills
vercel avatar

/flags-sdk

@e98c352
by vercelvercel/flags631 stars
93
Run it yourself

Implement feature flags in Next.js or SvelteKit code with the Flags SDK (`flags` npm package). Use when installing or configuring the SDK, declaring flags with `flag()`, setting up Project Connections, wiring a provider adapter (`@flags-sdk/vercel`, Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom), using `identify`, `dedupe`, or `evaluate`, keeping pages static with precompute, setting up Flags Explorer and the Vercel Toolbar, or encrypting flag values. Triggers: `flags/next`, `flags/sveltekit`, `flags/react`, `@flags-sdk/*`, `vercelAdapter`, precompute. For planning a flag, for Vercel Flags rollouts, experiments, and the `vercel flags` CLI, or for other frameworks, use the `vercel-flags` skill.

Use this Skill: https://skilld.dev/gh/vercel/flags/flags-sdk

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesproviders.md

≈5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Provider Adapters

Table of Contents


Vercel

Package: @flags-sdk/vercel

pnpm i flags @flags-sdk/vercel

Setup

Prerequisite: The Vercel CLI must be installed and authenticated. If it is not installed, run pnpm i -g vercel. For authentication or linking issues, follow the vercel-cli skill if it's already available. If it isn't, suggest the user install it with npx skills add vercel/vercel@vercel-cli (don't auto-install it) and rely on vercel <command> --help in the meantime.

The following steps integrate a flag into an app and need a linked project for vercel env pull (Set up the SDK, step 2). To only inspect or change remote flags, use the vercel-flags skill instead.

  1. Create a flag in the Vercel dashboard or via CLI: vercel flags create <flag-key> --kind boolean --description "<description>"
  2. Pull env vars: run vercel env pull to write the Vercel OIDC token and the Development FLAGS_SECRET to .env.local (Pull environment variables).
  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,
});

Define the entities and attributes under Flags → Entities in the dashboard before you use them in rules or segments, and return the same names from identify (Entities). The example above allows --by user.id / --by team.id in vercel flags split, rollout, and rules add, and the matching conditions in dashboard rules. Entities are evaluated fresh on every call; a rule whose attribute is missing from the context is skipped.

Attribute types

Each attribute has a type: String, Number, Boolean, String Array, or Timestamp. The value identify returns must match it.

  • Timestamp is a Unix epoch in milliseconds as a number (Date.now(), user.createdAt.getTime(), 1719792000000). Do not pass a Date, an ISO string, or seconds.
  • Timestamp rules only compare: is after / is before / is at or after / is at or before (gt / lt / gte / lte). Equality, one-of, and exists operators are not available for Timestamp attributes.
  • Timestamp attributes cannot bucket a split or rollout (--by); use them in rule conditions only.
  • To release at a certain time, pass the current time as system.time and compare against it in a rule. Keep Date.now() inside dedupe so every flag in the request sees the same time:
const identify = dedupe(async () => ({
  system: { time: Date.now() },
  user: { id: 'user-456', signupAt: 1719792000000 },
}));

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);
});

Project Connections

Check the installed @flags-sdk/vercel version before changing the code. Project Connections require version 1.6.0 or later; upgrade it if needed. The adapter includes the required core library version.

To read flags from another project in the same team, first grant the consumer project access from the source project's Flags → Connections page. Then pass the source project's ID:

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

const sharedAdapter = createVercelAdapter({ projectId: 'prj_source' });

export const sharedFeature = flag({
  key: 'shared-feature',
  adapter: sharedAdapter,
  defaultValue: false,
});

Use vercelAdapter alongside this adapter for the consumer's own flags. Both use the consumer's OIDC token; do not mint an SDK key for a connection. Run vercel env pull in the consumer project for local development. Connections apply across environments, and the token selects the source environment; custom environments use preview.

Verify access before you declare or render connected flags. A client whose first request is rejected with 401 does not retry; it serves defaultValue until the process restarts, with no visible error on the page:

  1. List the source project's connections: vercel flags connections list --project <source> --scope <team> --non-interactive. If the consumer project is missing, add it with vercel flags connections add <consumer> --project <source> --scope <team> --non-interactive.
  2. Confirm a real read with the consumer's credentials, outside the running app: a one-off script that calls createClient({ projectId: 'prj_source' }).evaluate('<flag-key>') from @vercel/flags-core, run with node --env-file=.env.local. Continue when it returns the flag's value. If it fails right after adding the connection, wait briefly and try again.
  3. Then add the flag() declarations and render them.

If a connected flag only ever returns its defaultValue, the client was likely rejected before access was in place. Fix access, then restart the dev server or redeploy.

For direct core access, use @vercel/flags-core version 1.11.0 or later with createClient({ projectId: 'prj_source' }). The projectId option cannot be combined with an SDK key. CLI management requires Vercel CLI version 63.0.0 or later; use the vercel-flags skill for the connection workflow, or see the CLI reference. See Project Connections for permissions and setup.

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(); // Vercel OIDC token, on deployments and after `vercel env pull`
const vercelAdapter = createVercelAdapter(vercelFlagsClient);

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

Outside Vercel, pass the SDK key: createClient(process.env.FLAGS). Unlike vercelAdapter(), createClient() does not read FLAGS on its own.

Core client in other frameworks (for example, Express)

Frameworks without a Flags SDK entrypoint use @vercel/flags-core directly instead of this SDK. The vercel-flags skill carries the example and the OIDC timing rules (Core SDK).

Managing flags

What a flag serves (enable, set, split, rollout, rules, segments, archive) is configured in the Vercel dashboard or with the vercel flags CLI, not in code. Keep the declaration in sync with the remote definition: the CLI key is the key in flag(), the kind matches the type parameter, options mirror the variants, and defaultValue is what the flag serves when it is archived or still a draft. The vercel-flags skill covers rollouts, experiments, promotion order, and the checks to run before archiving; vercel flags <cmd> --help lists the options.

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


Global Config

Package: @flags-sdk/global-config

pnpm i @flags-sdk/global-config

Env: GLOBAL_CONFIG="global-config-connection-string"

Usage

import { flag } from 'flags/next';
import { globalConfigAdapter } from '@flags-sdk/global-config';

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

Global Config should contain:

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

Custom configuration

import { createGlobalConfigAdapter } from '@flags-sdk/global-config';

const myAdapter = createGlobalConfigAdapter({
  connectionString: process.env.OTHER_GLOBAL_CONFIG,
  options: {
    globalConfigItemKey: '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, Global 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)
  • GLOBAL_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, always required:

  • POSTHOG_HOST (e.g. https://us.i.posthog.com or https://eu.i.posthog.com)
  • POSTHOG_PROJECT_API_KEY (phc_...)

Optional, opts into local evaluation (background polling) instead of remote:

  • POSTHOG_SECRET_KEY (phs_...)

For the Flags Explorer (getProviderData only):

  • POSTHOG_PERSONAL_API_KEY (phx_...)
  • POSTHOG_PROJECT_ID (e.g. 521742)

Methods

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

// Value — boolean flag. Pass the adapter uninvoked or invoked, both work.
export const myFlag = flag<boolean>({
  key: 'my-flag',
  adapter: postHogAdapter,
  identify,
});

// Value — multivariate flag resolves to the variant string
export const myVariant = flag<string>({
  key: 'my-flag',
  adapter: postHogAdapter,
  identify,
});

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

identify must return { distinctId }.

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.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>(),
});

Global 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);
  });
});

Flagsmith

Package: @flags-sdk/flagsmith

pnpm i @flags-sdk/flagsmith

Env: FLAGSMITH_ENVIRONMENT_KEY (required)

Remote evaluation is the default for serverless deployments. For a long-running server, use createFlagsmithAdapter({ environmentKey, enableLocalEvaluation: true }) with a server-side key to opt into local evaluation and environment polling. Call adapter.close() on shutdown to stop polling.

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;
      },
    };
  };
}

Bulk evaluation (bulkDecide)

Adapters can implement an optional bulkDecide hook. When set (and the adapter has an adapterId), evaluate() calls it once for every group of flags that share this adapter and the same identify source — instead of calling decide per flag. This lets the provider share work across evaluations (e.g. a single network request for many flags).

return {
  adapterId: 'my-provider', // required for bulkDecide to be used
  origin(key) {
    return `https://my-provider.com/flags/${key}`;
  },
  async decide({ key }): Promise<ValueType> {
    return false as ValueType;
  },
  // Called by evaluate() for a batch of flags sharing this adapter + identify
  async bulkDecide({ flags, entities, headers, cookies }) {
    // flags: { key: string; defaultValue?: unknown }[]
    // Return a record keyed by flag key.
    return Object.fromEntries(
      flags.map(({ key }) => [key, false as ValueType]),
    );
  },
};

Contract:

  • Return Record<flagKey, value>. Missing keys or value: undefined fall back to each flag's defaultValue.
  • Throwing falls back to defaultValue per flag (and rejects for flags without a defaultValue).
  • A flag with an inline decide takes precedence and is excluded from bulk evaluation.

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,
});

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings6d5 checks · Risk SAFE
  • Gen Agent Trust Hub7d

    This skill facilitates the implementation of feature flags using the Vercel Flags SDK. It involves standard developer workflows such as package installation, CLI-based project linking, and environment variable management. Security considerations include the handling of sensitive secrets and the exposure of flag metadata via a discovery endpoint, both of which are addressed with recommended best practices in the documentation. See detailed analysis for context.

  • Socket6d

    No alerts

  • Snyk7d

    Risk: LOW · No issues

  • Runlayer8mo

    3/5 files flagged

  • ZeroLeaks7mo

    3 findings · Score: 51/100

Signed by skilld at e98c352. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 hours ago.

Activeupdated yesterday

README badge

README badge for vercel/flags/flags-sdk