Flags SDK

Flags SDK (flags npm パッケージ) は、Next.js と SvelteKit 向けのフィーチャーフラグツールキットです。各フィーチャーフラグを呼び出し可能な関数に変え、アダプターを通じてあらゆるフラグプロバイダーで動作し、precompute パターンを使用してページを静的に保ちます。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();

サーバーサイド評価

フラグはサーバーサイドで評価されるため、レイアウトシフトを回避し、ページを静的に保ち、機密性を維持します。ルーティングミドルウェアを precompute パターンと組み合わせて、CDN から静的バリエーションを提供します。

アダプターパターン

アダプターはフラグ宣言の decide と origin を置き換え、フラグをプロバイダーに接続します。Vercel Flags (@flags-sdk/vercel) は初期プロバイダーアダプターです。サードパーティアダプターは Statsig、LaunchDarkly、PostHog などで利用できます。

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

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

エージェント ワークフロー：新しいフラグの作成

ユーザーがフィーチャーフラグの作成または追加をリクエストするとき、以下のステップを順番に実行してください。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 をスキップしてください

ステップ

1. パッケージをインストール (package.json にまだない場合)：

   pnpm i flags @flags-sdk/vercel
   

2. フラグを 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 を実行してください。

3. 環境変数をプル：vercel env pull を実行して、FLAGS と FLAGS_SECRET を .env.local に書き込みます。これらの環境変数がないと、vercelAdapter() はフラグを評価できません。このステップはフラグ作成後に 必須 です。

4. コードでフラグを宣言：vercelAdapter() を使用して flags.ts に追加してください (ファイルが存在しない場合は作成してください)：

   import { flag } from 'flags/next';
   import { vercelAdapter } from '@flags-sdk/vercel';
   
   export const myFlag = flag({
     key: 'my-flag',
     adapter: vercelAdapter(),
   });
   

5. フラグを使用：ページまたはコンポーネントで呼び出し、結果に基づいて条件付きでレンダリングします：

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

6. Vercel Toolbar をセットアップ (まだ存在しない場合)：

   • pnpm i @vercel/toolbar を実行
   • next.config.ts をツールバープラグインでラップ
   • ルートレイアウトで <VercelToolbar /> をレンダリング 完全なコードについては、references/nextjs.md — Toolbar Setup を参照してください。

7. Flags Explorer をセットアップ (まだ存在しない場合)：app/.well-known/vercel/flags/route.ts を作成してください — 以下の Flags Explorer セットアップ セクションを参照してください。

Vercel Flags

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: 'Show promotional banner',
  defaultValue: false,
  options: [
    { value: false, label: 'Hide' },
    { value: true, label: 'Show' },
  ],
  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 }[]	可能な値、precompute + Flags Explorer で使用
adapter	Adapter	decide と origin を実装するプロバイダーアダプター
identify	function	decide の評価コンテキスト (エンティティ) を返す

Dedupe

共有関数 (特に 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 { createFlagsDiscoveryEndpoint } from 'flags/next';
import { getProviderData } from '@flags-sdk/vercel';
import * as flags from '../../../../flags';

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

外部プロバイダーデータ付き

サードパーティプロバイダーを Vercel Flags と共に使用する場合、mergeProviderData でそれらのデータを組み合わせます。各プロバイダーアダプターは独自の getProviderData をエクスポートします — 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

precompute と Flags Explorer に必須です。32 ランダムバイト、base64 エンコード必須：

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

各環境 (Development、Preview、Production) に別々の FLAGS_SECRET 値を使用し、Preview と Production の値を Sensitive にマークします。環境ごとに一度ジェネレーターを実行して異なる値を生成し、各値を 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>

その後、vc env pull を実行してローカルに同期してください。

Precompute パターン

precompute を使用してフィーチャーフラグを使用しながらページを静的に保ちます。ミドルウェアはフラグを評価し、リライトを通じて URL に結果をエンコードします。ページは precompute 値を読み取り、再評価しません。

高レベルのフロー：

1. フラグを宣言して配列にグループ化
2. ミドルウェアで precompute(flagGroup) を呼び出し、code 文字列を取得
3. リクエストを /${code}/original-path にリライト
4. ページはコードからフラグ値を読み取ります：await myFlag(code, flagGroup)

完全な実装の詳細については、フレームワーク固有のリファレンスを参照してください：

• Next.js：references/nextjs.md を参照 — プロキシミドルウェア、precompute セットアップ、ISR、generatePermutations、複数グループをカバー
• SvelteKit：references/sveltekit.md を参照 — reroute フック、ミドルウェア、precompute セットアップ、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} />;
}

React コンポーネント

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

// Flags Explorer 用のフラグ値でスクリプトタグをレンダリング
<FlagValues values={{ myFlag: true }} />

// Flags Explorer 用のフラグ定義でスクリプトタグをレンダリング
<FlagDefinitions definitions={{ myFlag: { options: [...], description: '...' } }} />

リファレンス

詳細なフレームワークとプロバイダーガイドは、コンテキストを精簡するために別ファイルに記載されています：

• references/nextjs.md：Next.js クイックスタート、ツールバー、App Router、Pages Router、ミドルウェア/プロキシ、precompute、dedupe、ダッシュボードページ、マーケティングページ、suspense フォールバック
• references/sveltekit.md：SvelteKit クイックスタート、ツールバー、フック セットアップ、reroute + ミドルウェア付き precompute、ダッシュボードページ、マーケティングページ
• 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 リファレンス