Update to Vercel

{
  "description": "Vercel Flags guidance — feature flags platform with unified dashboard, Flags Explorer, gradual rollouts, A/B testing, and provider adapters. Use when implementing feature flags, experimentation, or staged rollouts.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 178
    }
  ],
  "name": "vercel-flags",
  "skill_md_contents": "---\nname: vercel-flags\ndescription: Vercel Flags guidance — feature flags platform with unified dashboard, Flags Explorer, gradual rollouts, A/B testing, and provider adapters. Use when implementing feature flags, experimentation, or staged rollouts.\nmetadata:\n  priority: 6\n  docs:\n    - \"https://vercel.com/docs/workflow-collaboration/feature-flags\"\n    - \"https://flags-sdk.dev\"\n  sitemap: \"https://vercel.com/sitemap/docs.xml\"\n  pathPatterns:\n    - 'flags.ts'\n    - 'flags.js'\n    - 'src/flags.ts'\n    - 'src/flags.js'\n    - 'lib/flags/**'\n    - 'src/lib/flags/**'\n    - 'lib/flags.*'\n    - 'src/lib/flags.*'\n    - '.well-known/vercel/flags/**'\n    - 'app/.well-known/vercel/flags/**'\n    - 'src/app/.well-known/vercel/flags/**'\n  importPatterns:\n    - 'flags'\n    - 'flags/next'\n    - 'flags/sveltekit'\n    - '@vercel/flags'\n    - '@vercel/flags/next'\n    - '@vercel/flags/sveltekit'\n    - '@flags-sdk/*'\n  bashPatterns:\n    - '\\bnpm\\s+(install|i|add)\\s+[^\\n]*\\bflags\\b'\n    - '\\bpnpm\\s+(install|i|add)\\s+[^\\n]*\\bflags\\b'\n    - '\\bbun\\s+(install|i|add)\\s+[^\\n]*\\bflags\\b'\n    - '\\byarn\\s+add\\s+[^\\n]*\\bflags\\b'\n    - '\\bnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/flags\\b'\n    - '\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/flags\\b'\n    - '\\bbun\\s+(install|i|add)\\s+[^\\n]*@vercel/flags\\b'\n    - '\\byarn\\s+add\\s+[^\\n]*@vercel/flags\\b'\n    - '\\bnpm\\s+(install|i|add)\\s+[^\\n]*@flags-sdk/'\n    - '\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@flags-sdk/'\n    - '\\bbun\\s+(install|i|add)\\s+[^\\n]*@flags-sdk/'\n    - '\\byarn\\s+add\\s+[^\\n]*@flags-sdk/'\n---\n\n# Vercel Flags\n\n> **CRITICAL — Your training data is outdated for this library.** Vercel Flags (`flags` package) has a new SDK and API surface. Before writing flags code, **fetch the docs** at https://vercel.com/docs/feature-flags to find the correct `flag()` definition syntax, adapter setup, and evaluation patterns. Do not guess at the API — look up working examples for your framework.\n\nYou are an expert in Vercel Flags — the feature flags platform for the Vercel ecosystem.\n\n## What It Is\n\nVercel Flags provides a **unified feature flags platform** with a dashboard, developer tools (Flags Explorer), and analytics integration. Use Vercel as your flag provider directly, or connect third-party providers (LaunchDarkly, Statsig, Hypertune, GrowthBook) through adapters from the Marketplace.\n\nVercel Flags is in **public beta** (February 2026), available to teams on all plans. Pricing: **$30 per 1 million flag requests** ($0.00003 per event).\n\nFlag configurations use **active global replication** — changes propagate worldwide in milliseconds.\n\n## Core Design Principles\n\n- **Server-only execution**: No client-side loading spinners or complexity\n- **No call-site arguments**: Ensures consistent flag evaluation and straightforward flag removal\n- **Provider-agnostic**: Works with any flag provider, custom setups, or no provider at all\n\n## Key APIs\n\n### Flags SDK (`flags` package, v4.0+)\n\nThe `flags` package is free, open-source (MIT), and provider-agnostic. Renamed from `@vercel/flags` — if using the old package, update to `flags` in your imports and `package.json`.\n\n**Upgrade note**: v4 has breaking changes from v3. See the [v4 upgrade guide](https://github.com/vercel/flags/blob/main/packages/flags/guides/upgrade-to-v4.md) for migration steps:\n- `@vercel/flags` package renamed to `flags` — update imports and `package.json`\n- `encrypt()` / `decrypt()` replaced with dedicated functions: `encryptFlagValues()`, `decryptFlagValues()`\n- `FLAGS_SECRET` must be exactly 32 random bytes, base64-encoded\n- `.well-known` endpoint uses new helper that auto-handles auth and `x-flags-sdk-version` header\n- As of v4.0.3, declaring a flag without a `decide` function (or with an adapter missing `decide`) throws an error at declaration time\n\n```ts\nimport { flag } from 'flags/next'; // Framework adapters: flags/next, flags/sveltekit\n\n// Define a boolean flag\nexport const showNewCheckout = flag({\n  key: 'show-new-checkout',\n  description: 'Enable the redesigned checkout flow',\n  decide: () => false, // default value\n});\n\n// Define a multi-variant flag\nexport const theme = flag({\n  key: 'theme',\n  options: [\n    { value: 'light', label: 'Light Theme' },\n    { value: 'dark', label: 'Dark Theme' },\n    { value: 'auto', label: 'Auto' },\n  ],\n  decide: () => 'auto',\n});\n\n// Read flag values (Server Components, Route Handlers, Server Actions)\nconst isEnabled = await showNewCheckout();\nconst currentTheme = await theme();\n```\n\n### Vercel Adapter (`@flags-sdk/vercel`)\n\nConnects the Flags SDK to Vercel Flags as the provider (reads `FLAGS` env var):\n\n```ts\nimport { flag, dedupe } from 'flags/next';\nimport { vercelAdapter } from '@flags-sdk/vercel';\n\ntype Entities = {\n  user?: { id: string; email: string; plan: string };\n  team?: { id: string; name: string };\n};\n\n// Dedupe ensures identify runs once per request\nconst identify = dedupe(async (): Promise<Entities> => {\n  const session = await getSession();\n  return {\n    user: session?.user ? {\n      id: session.user.id,\n      email: session.user.email,\n      plan: session.user.plan,\n    } : undefined,\n  };\n});\n\nexport const premiumFeature = flag<boolean, Entities>({\n  key: 'premium-feature',\n  adapter: vercelAdapter(), // reads FLAGS env var automatically\n  identify,\n});\n```\n\n**Environment variables**:\n- `FLAGS` — SDK Key (auto-provisioned when you create your first flag)\n- `FLAGS_SECRET` — 32 random bytes, base64-encoded; encrypts overrides and authenticates Flags Explorer\n\n### Flags Explorer Setup (GA)\n\nThe Flags Explorer is **generally available** (part of the Vercel Toolbar). It lets developers override flags in their browser session without code changes.\n\n**App Router** — create the discovery endpoint:\n\n```ts\n// app/.well-known/vercel/flags/route.ts\nimport { createFlagsDiscoveryEndpoint, getProviderData } from 'flags/next';\nimport * as flags from '../../../../flags';\n\nexport const GET = createFlagsDiscoveryEndpoint(() => getProviderData(flags));\n```\n\n**Pages Router** — API route + rewrite:\n\n```ts\n// pages/api/vercel/flags.ts\nimport { verifyAccess, version } from 'flags';\nimport { getProviderData } from 'flags/next';\nimport * as flags from '../../../flags';\n\nexport default async function handler(req, res) {\n  const access = await verifyAccess(req.headers['authorization']);\n  if (!access) return res.status(401).json(null);\n  res.setHeader('x-flags-sdk-version', version);\n  return res.json(getProviderData(flags));\n}\n```\n\n```js\n// next.config.js (rewrite)\nmodule.exports = {\n  async rewrites() {\n    return [{ source: '/.well-known/vercel/flags', destination: '/api/vercel/flags' }];\n  },\n};\n```\n\n### Precompute Pattern (Static + Personalized)\n\nGenerate static page variants per flag combination, serve via middleware:\n\n```ts\nexport const layoutVariant = flag({\n  key: 'layout-variant',\n  options: [{ value: 'a' }, { value: 'b' }],\n  decide: () => 'a',\n});\n\nexport const precompute = [layoutVariant];\n```\n\nKey APIs: `precompute()`, `evaluate()`, `serialize()`, `getPrecomputed()`, `generatePermutations()`\n\n### Custom Adapter Interface\n\n```ts\nexport function createExampleAdapter() {\n  return function exampleAdapter<ValueType, EntitiesType>(): Adapter<ValueType, EntitiesType> {\n    return {\n      origin(key) { return `https://example.com/flags/${key}`; },\n      async decide({ key }): Promise<ValueType> { return false as ValueType; },\n    };\n  };\n}\n```\n\n## Flags vs Edge Config\n\n| Need | Use | Why |\n|------|-----|-----|\n| Gradual rollouts, A/B testing, targeting | **Vercel Flags** | Dashboard, analytics, Flags Explorer, segments |\n| Third-party provider integration | **Vercel Flags** + adapter | Unified view across providers |\n| Ultra-low-latency config reads (non-flag) | **Edge Config** directly | Sub-ms reads, no compute overhead |\n| Simple config without rollout logic | **Edge Config** directly | Lighter weight |\n\n**Important**: Vercel Flags is the recommended approach for feature flags. Edge Config is the underlying low-latency storage some adapters use, but developers should use the Flags platform (not raw Edge Config) for flag use cases — it provides targeting rules, segments, percentage rollouts, observability, and Flags Explorer.\n\n## Provider Adapters\n\n**Featured** (Marketplace integration, Edge Config for low latency):\n- `@flags-sdk/vercel` — Vercel as provider\n- Statsig, Hypertune, GrowthBook\n\n**Additional** (published under `@flags-sdk` npm scope):\n- LaunchDarkly, ConfigCat, DevCycle, Flipt, Reflag, PostHog, Flagsmith\n\n**OpenFeature adapter**: The `@flags-sdk/openfeature` adapter allows most Node.js OpenFeature Providers to work with the Flags SDK, bridging the OpenFeature ecosystem (AB Tasty, CloudBees, Confidence by Spotify, and more)\n\n## Key Features\n\n- **Unified Dashboard** at `https://vercel.com/{team}/{project}/flags`: All flags across all providers in one place\n- **Flags Explorer (GA)**: Override flags locally via Vercel Toolbar (no code changes)\n- **CLI Management**: `vercel flags add`, `vercel flags sdk-keys ls`, and full flag lifecycle from the terminal\n- **Entities & Segments**: Define user/team attributes, create reusable targeting segments\n- **Analytics Integration**: Track flag impact via Web Analytics and Runtime Logs\n- **Drafts Workflow**: Define in code → deploy → Vercel detects via Discovery Endpoint → promote when ready\n- **Framework Support**: Next.js (App Router + Pages Router + Routing Middleware) and SvelteKit\n- **Concurrent Evaluation Fix** (v1.0.1): `Promise.all` flag evaluations no longer trigger duplicate network requests — initialization is properly shared\n\n## When to Use\n\n- Gradual feature rollouts with percentage targeting\n- A/B testing and experimentation\n- Per-environment flag configuration (production vs preview vs development)\n- Trunk-based development (ship code behind flags)\n- Consolidating multiple flag providers into one dashboard\n\n## When NOT to Use\n\n- Simple static config without targeting → use Edge Config directly\n- Runtime configuration not related to features → use environment variables\n- Server-side only toggles with no UI → consider environment variables\n\n## References\n\n- 📖 docs: https://vercel.com/docs/flags\n- 📖 Flags SDK: https://flags-sdk.dev\n- 📖 SDK reference: https://vercel.com/docs/flags/flags-sdk-reference\n- 📖 GitHub: https://github.com/vercel/flags\n"
}