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.

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

// Usage: just call the function
const value = await exampleFlag();

Server-Side Evaluation

Evaluate flags server-side to avoid layout shift, keep pages static, and maintain confidentiality. Use routing middleware + precompute to serve static variants from CDN.

Adapter Pattern

Adapters replace

decide

and

origin

on a flag declaration, enabling provider-agnostic flags:

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

Declaring Flags

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;

decide

receives the entities:

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 Adapter

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

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

Key Parameters

Parameter	Type	Description
`key`	`string`	Unique flag identifier
`decide`	`function`	Resolves the flag value
`defaultValue`	`any`	Fallback if `decide` returns undefined or throws
`description`	`string`	Shown in Flags Explorer
`origin`	`string`	URL to manage the flag in provider dashboard
`options`	`{ label?: string, value: any }[]`	Possible values, used for precompute + Flags Explorer
`adapter`	`Adapter`	Provider adapter implementing `decide` and `origin`
`identify`	`function`	Returns evaluation context (entities) for `decide`

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 { getProviderData, createFlagsDiscoveryEndpoint } from 'flags/next';
import * as flags from '../../../../flags';

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

With External Provider Data

import { getProviderData, createFlagsDiscoveryEndpoint } from 'flags/next';
import { getProviderData as getStatsigProviderData } from '@flags-sdk/statsig';
import { mergeProviderData } from 'flags';
import * as flags 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,
    }),
  ]);
});

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'))"

Store as

FLAGS_SECRET

env var. On Vercel:

vc env add FLAGS_SECRET

then

vc env pull

Precompute Pattern (Overview)

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:

Declare flags and group them in an array
Call
```
precompute(flagGroup)
```
in middleware, get a
```
code
```
string
Rewrite request to
```
/${code}/original-path
```
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 returning an object with

origin

and

decide

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> {
        // evaluate against your provider
        return false as ValueType;
      },
    };
  };
}

Encryption Functions

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

Function	Purpose
`encryptFlagValues`	Encrypt resolved flag values
`decryptFlagValues`	Decrypt flag values
`encryptFlagDefinitions`	Encrypt flag definitions/metadata
`decryptFlagDefinitions`	Decrypt flag definitions
`encryptOverrides`	Encrypt toolbar overrides
`decryptOverrides`	Decrypt toolbar overrides

All use

FLAGS_SECRET

by default. Example:

tsx

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

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

React Components

tsx

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: Next.js quickstart, App Router, Pages Router, middleware/proxy, precompute, dedupe, dashboard pages, marketing pages, suspense fallbacks
references/sveltekit.md: SvelteKit quickstart, hooks setup, toolbar, precompute with reroute + middleware, dashboard pages, marketing pages
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: Full API reference for
```
flags
```
,
```
flags/react
```
,
```
flags/next
```
, and
```
flags/sveltekit
```

flags-sdk

NPX Install

Tags

SKILL.md Content