Flags SDK：Next.js和SvelteKit功能开关工具包，支持Vercel等提供商

flags-sdk by vercel/flags

344 周安装量

574 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/vercel/flags --skill flags-sdk

云服务 JavaScript 框架开发运维

🇨🇳中文介绍

Flags SDK

Flags SDK (flags npm 包) 是一个用于 Next.js 和 SvelteKit 的功能开关工具包。它将每个功能开关转换为可调用的函数，通过适配器与任何开关提供商协同工作，并使用预计算模式保持页面静态。Vercel Flags 是第一方提供商，允许您从 Vercel 仪表板或 vercel flags CLI 管理开关。

文档：https://flags-sdk.dev
仓库：https://github.com/vercel/flags

核心概念

代码即开关

每个开关都声明为一个函数。调用处无需字符串键：

import { flag } from 'flags/next';

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

const value = await exampleFlag();

服务端评估

开关在服务端进行评估，以避免布局偏移、保持页面静态并维护机密性。将路由中间件与预计算模式结合，从 CDN 提供静态变体。

适配器模式

适配器替换开关声明中的 decide 和 origin，将您的开关连接到提供商。Vercel Flags () 是第一方适配器。第三方适配器可用于 Statsig、LaunchDarkly、PostHog 等。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

代理工作流：创建新开关

当用户要求您创建或添加功能开关时，请按顺序执行以下步骤。不要将 CLI 步骤作为“后续步骤”留给用户——请自行执行。

检查项目状态以调整命令并决定可以跳过哪些步骤：

存在哪个锁文件 (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb)？ → 相应地调整所有包管理器命令 (pnpm add, npm install, yarn add, bun add)。
package.json 中是否有 flags？ → 跳过安装（步骤 1）
是否存在 .vercel/ 目录？ → 项目已链接，跳过步骤 2 中的 vercel link
.env.local 是否包含 FLAGS=？ → 环境变量已拉取，跳过步骤 3
是否存在 flags.ts（或 lib/flags.ts, src/flags.ts）？ → 添加到现有文件而不是从头创建（步骤 4）
package.json 中是否有 @vercel/toolbar？ → 跳过工具栏设置（步骤 6）
是否存在 app/.well-known/vercel/flags/route.ts？ → Flags Explorer 已设置，跳过步骤 7

安装包（如果尚未在 package.json 中）：
```
pnpm i flags @flags-sdk/vercel
```
向 Vercel 注册开关：运行 vercel flags add <flag-key> --kind boolean --description "<description>"。

前提条件：vercel flags 命令要求安装并验证 Vercel CLI。如果未安装 Vercel CLI，请运行 pnpm i -g vercel。对于身份验证或链接问题，请阅读并遵循 vercel-cli 技能。如果未安装，请运行 npx skills add https://github.com/vercel/vercel --skill vercel-cli。

在运行 vercel flags add 之前，请验证项目是否已链接到 Vercel。检查项目根目录中是否存在 .vercel 目录。如果不存在，请先运行 vercel link。
拉取环境变量：运行 vercel env pull 将 FLAGS 和 FLAGS_SECRET 写入 .env.local。没有这些环境变量，vercelAdapter() 将无法评估开关。创建开关后，此步骤是强制性的。

在代码中声明开关：使用 vercelAdapter() 将其添加到 flags.ts（如果文件不存在则创建）：

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

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

使用开关：在您的页面或组件中调用它，并根据结果有条件地渲染：

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

export default async function Page() {
  const enabled = await myFlag();
  return <div>{enabled ? '功能开启' : '功能关闭'}</div>;
}

设置 Vercel 工具栏（如果尚未存在）：
- 运行 pnpm i @vercel/toolbar
- 用工具栏插件包装 next.config.ts
- 在根布局中渲染 <VercelToolbar /> 完整代码请参见 references/nextjs.md — 工具栏设置。
设置 Flags Explorer（如果尚未存在）：创建 app/.well-known/vercel/flags/route.ts — 请参阅下面的 Flags Explorer 设置部分。

Vercel Flags 是 Vercel 的功能开关平台。您可以从 Vercel 仪表板或 vercel flags CLI 创建和管理开关，然后使用 @flags-sdk/vercel 适配器将它们连接到您的代码。当您在 Vercel 中创建开关时，FLAGS 和 FLAGS_SECRET 环境变量会自动配置。

要端到端创建开关，请遵循上述代理工作流。

完整的 Vercel 提供商参考——用户定位、vercel flags CLI 子命令、自定义适配器配置和 Flags Explorer 设置——请参见 references/providers.md。

使用 Vercel Flags 时，请按照代理工作流中所示使用 vercelAdapter() 声明开关。对于其他提供商，请参见 references/providers.md。以下是通用的 flag() 模式。

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

export const showBanner = flag<boolean>({
  key: 'show-banner',
  description: '显示推广横幅',
  defaultValue: false,
  options: [
    { value: false, label: '隐藏' },
    { value: true, label: '显示' },
  ],
  decide() { return false; },
});

带评估上下文的开关

使用 identify 来建立请求的对象。返回的实体将传递给 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);
  },
});

使用其他适配器的开关

适配器将开关连接到第三方提供商。每个适配器替换 decide 和 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,
});

所有支持的适配器请参见 references/providers.md。

参数	类型	描述
`key`	`string`	唯一的开关标识符
`decide`	`function`	解析开关值
`defaultValue`	`any`	如果 `decide` 返回 undefined 或抛出异常时的回退值
`description`	`string`	在 Flags Explorer 中显示
`origin`	`string`	在提供商仪表板中管理开关的 URL
`options`	`{ label?: string, value: any }[]`	可能的值，用于预计算 + Flags Explorer
`adapter`	`Adapter`	实现 `decide` 和 `origin` 的提供商适配器
`identify`	`function`	返回 `decide` 的评估上下文（实体）

将共享函数（尤其是 identify）包装在 dedupe 中，以便每个请求只运行一次：

import { dedupe } from 'flags/next';

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

注意：dedupe 在 Pages Router 中不可用。

Flags Explorer 设置

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

使用外部提供商数据

当同时使用第三方提供商和 Vercel Flags 时，使用 mergeProviderData 合并它们的数据。每个提供商适配器都导出自己的 getProviderData — 请参见 references/providers.md 中的提供商特定示例。

// 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 Explorer 所必需。必须是 32 个随机字节，base64 编码：

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

存储为 FLAGS_SECRET 环境变量。在 Vercel 上：vc env add FLAGS_SECRET 然后 vc env pull。

使用预计算可以在使用功能开关的同时保持页面静态。中间件评估开关并通过重写将结果编码到 URL 中。页面读取预计算的值而不是重新评估。

声明开关并将它们分组到数组中
在中间件中调用 precompute(flagGroup)，获取 code 字符串
将请求重写到 /${code}/original-path
页面从 code 读取开关值：await myFlag(code, flagGroup)

完整的实现细节，请参见特定框架的参考：

Next.js：参见 references/nextjs.md — 涵盖代理中间件、预计算设置、ISR、generatePermutations、多组
SvelteKit：参见 references/sveltekit.md — 涵盖重路由钩子、中间件、预计算设置、ISR、预渲染

创建一个适配器工厂，返回一个包含 origin 和 decide 的对象。完整模式（包括默认适配器和单例客户端示例），请参见 references/providers.md。

用于在浏览器中保持开关数据机密性（由 Flags Explorer 使用）：

函数	用途
`encryptFlagValues`	加密已解析的开关值
`decryptFlagValues`	解密开关值
`encryptFlagDefinitions`	加密开关定义/元数据
`decryptFlagDefinitions`	解密开关定义
`encryptOverrides`	加密工具栏覆盖
`decryptOverrides`	解密工具栏覆盖

默认情况下都使用 FLAGS_SECRET。示例：

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

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

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

// 为 Flags Explorer 渲染包含开关值的 script 标签
<FlagValues values={{ myFlag: true }} />

// 为 Flags Explorer 渲染包含开关定义的 script 标签
<FlagDefinitions definitions={{ myFlag: { options: [...], description: '...' } }} />

详细的框架和提供商指南在单独的文件中，以保持上下文简洁：

references/nextjs.md：Next.js 快速入门、工具栏、App Router、Pages Router、中间件/代理、预计算、去重、仪表板页面、营销页面、Suspense 回退
references/sveltekit.md：SvelteKit 快速入门、工具栏、钩子设置、使用重路由 + 中间件的预计算、仪表板页面、营销页面
references/providers.md：所有提供商适配器 — Vercel、Edge Config、Statsig、LaunchDarkly、PostHog、GrowthBook、Hypertune、Flagsmith、Reflag、Split、Optimizely、OpenFeature 和自定义适配器
references/api.md：flags、flags/react、flags/next 和 flags/sveltekit 的完整 API 参考

🇺🇸English

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 in step 2

Steps

Install packages (if not already in package.json):
```
pnpm i flags @flags-sdk/vercel
```
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.

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.

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

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

Parameter	Type	Description
`key`	`string`	Unique flag identifier
`decide`	`function`	Resolves the flag value
`defaultValue`	`any`	Fallback if `decide` returns undefined or throws

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

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

Store as FLAGS_SECRET env var. On Vercel: vc env add FLAGS_SECRET then vc env pull.

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:

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 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):

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`

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 : Next.js quickstart, toolbar, App Router, Pages Router, middleware/proxy, precompute, dedupe, dashboard pages, marketing pages, suspense fallbacks
references/sveltekit.md : SvelteKit quickstart, toolbar, hooks setup, 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

Weekly Installs

344

Repository

vercel/flags

GitHub Stars

574

First Seen

Feb 27, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

amp341

gemini-cli341

codex341

kimi-cli340

cursor340

opencode340

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

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

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.

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

Flags SDK：Next.js和SvelteKit功能开关工具包，支持Vercel等提供商

🇨🇳中文介绍

Flags SDK

核心概念

代码即开关

服务端评估

适配器模式

相关 Skills

代理工作流：创建新开关

开始之前

步骤

Vercel Flags

声明开关

基础开关

带评估上下文的开关

使用其他适配器的开关

关键参数

去重

Flags Explorer 设置

Next.js (App Router)

使用外部提供商数据

SvelteKit

FLAGS_SECRET

预计算模式

自定义适配器

加密函数

React 组件

参考

🇺🇸English

Flags SDK

Core concepts

Flags as code

Server-side evaluation

Adapter pattern

Agent workflow: Creating a new flag

Before you start

Steps

Vercel Flags

Declaring flags

Basic flag

Flag with evaluation context

Flag with another adapter

Key parameters

Dedupe

Flags Explorer setup

Next.js (App Router)

With external provider data

SvelteKit

FLAGS_SECRET

Precompute pattern

Custom adapters

Encryption functions

React components

References

最新 Skills