Flags SDK

The Flags SDK (flags npm package) is a feature flags toolkit designed for Next.js and SvelteKit. It allows you to treat feature flags as callable functions, enabling server-side evaluation to prevent layout shifts and maintain page performance. It uses an adapter pattern to connect to various providers, including Vercel Flags (the first-party provider), Statsig, LaunchDarkly, and others.

import { flag } from 'flags/next';

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

const value = await exampleFlag();

Geistdocs is a modern documentation template built using Next.js and Fumadocs. It is designed to help developers quickly deploy Vercel documentation sites with a consistent UI and built-in features like AI chat and GitHub Discussions integration.

Key features include:

• MDX-powered documentation: Full support for writing docs using MDX components.
• AI-powered chat: An integrated AI assistant trained on your documentation.
• GitHub Discussions integration: Enables users to provide feedback directly via GitHub.
• Advanced search: Fast, fuzzy search capabilities across all documentation.
• Modern UI: Accessible components built with Radix UI, featuring dark mode and responsive design.
• Performance: Built on Next.js 16 with App Router and includes built-in RSS feeds.

Providers in the Flags SDK ecosystem are categorized by their capabilities:

• Adapter: Enables flag and experiment evaluation using the Flags SDK.
• Flags Explorer: Enables the display of flag metadata (such as descriptions) within the Flags Explorer.
• Marketplace: Providers available via the Vercel Marketplace.
• Global Config: Enables reading feature flags from a Global Config for low latency.

When using Next.js Partial Prerendering, combining it with precomputed flags allows the deployment of multiple static shells. For a single route, the system can generate:

1. A shell containing the unauthenticated skeleton.
2. A shell containing the authenticated skeleton.

This allows marketing pages or landing pages to be served statically without blocking the response on slow auth state resolution, while still providing a seamless transition (streaming the auth state) once it is resolved.

When declaring a flag using flag(), you define its defaultValue and how its evaluation context is established via the identify() method. This centralizes the logic for context creation, preventing the need to manually pass user or session data at every call site, which reduces the risk of inconsistent evaluations across the codebase.

import { flag } from 'flags/next';

export const exampleFlag = flag({
  key: 'example-flag',
  defaultValue: false,
  // Establishes the evaluation context centrally
  identify() {
    return { user: { id: '123' } };
  },
  // Uses the established context to decide the flag value
  decide({ entities }) {
    return entities.user.id === '123';
  },
});

Using many feature flags or flags with many possible values leads to an exponential increase in permutations. This can increase build times (if using build-time rendering) or decrease cache hit rates (if using lazy ISR generation).

To mitigate this, you can manually specify which permutations to generate at build time by passing a second argument to generatePermutations. All other permutations will be generated on demand the first time they are requested.

Evaluation context allows you to decouple user identification from feature flag decision-making.

1. identify: A function that returns an object representing the user or environment (the "entities").
2. decide: A function that receives those entities as an argument and returns the flag's value (e.g., true or false).

This pattern allows you to segment features based on any criteria, such as user IDs, roles, or device types.

import { flag } from 'flags/next';

export const exampleFlag = flag<boolean>({
  key: 'identify-example-flag',
  identify() {
    // Returns the entities used for evaluation
    return { user: { id: 'user1' } };
  },
  decide({ entities }) {
    // Uses the entities to make a decision
    return entities?.user?.id === 'user1';
  },
});

To evaluate flags based on user identity (e.g., user IDs from cookies), use the identify property in the flag configuration.

identify is a function that receives normalized headers and cookies and returns an object of Entities. These entities are then passed to the decide function. You can use dedupe to ensure the identify logic runs only once per request.

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

Feature flag evaluation is the process of determining a flag's value based on two inputs:

1. Definition: The rules for evaluation (e.g., which users get a feature), typically loaded from a feature flag provider.
2. Evaluation Context: Data about the specific user or entity being evaluated.

The relationship is expressed as: evaluate(definition, evaluation context) = value

Flags that are globally on or off do not require an evaluation context, but flags targeting specific user segments do.