diff --git a/apps/docs/content/docs/providers/vercel.mdx b/apps/docs/content/docs/providers/vercel.mdx index 40fcfa60..7cc021c7 100644 --- a/apps/docs/content/docs/providers/vercel.mdx +++ b/apps/docs/content/docs/providers/vercel.mdx @@ -4,8 +4,8 @@ title: 'Vercel Flags' Vercel Flags is a feature flag provider built into Vercel's platform, allowing you to manage flags directly in your Vercel projects. The `@flags-sdk/vercel` package connects the Flags SDK to Vercel Flags. - - Connect my existing Flags SDK setup to Vercel Flags. Install `@flags-sdk/vercel`, run `vercel env pull` so `.env.local` has the Vercel OIDC token and `FLAGS_SECRET`, update my flag declarations to use `vercelAdapter`, add or reuse an `identify` function for targeting entities, create the Flags Explorer discovery endpoint, and run the relevant type checks or build when finished. Use OIDC for this project's flags. To read another same-team project's flags, first configure a Project Connection, then use `createVercelAdapter({ projectId })` with the source project's ID. For an app outside Vercel, pass an SDK key to `createVercelAdapter`. + + Connect my existing Flags SDK setup to Vercel Flags. Install `@flags-sdk/vercel`, run `vercel env pull` so `.env.local` has the Vercel OIDC token and `FLAGS_SECRET`, update my flag declarations to use `vercelAdapter`, add or reuse an `identify` function for targeting entities, create the Flags Explorer discovery endpoint, and run the relevant type checks or build when finished. Use OIDC for this project's flags. To read another same-team project's flags, use `@flags-sdk/vercel` version 1.6.0 or later, configure a Project Connection, then use `createVercelAdapter({ projectId })` with the source project's ID. For an app outside Vercel, pass an SDK key to `createVercelAdapter`. @@ -148,7 +148,7 @@ This endpoint allows Flags Explorer to: ### Read a connected project's flags -Project Connections let your project read flags from another project in the same team without an SDK key. In the source project's **Flags → Connections** page, grant your project access. Then pass the source project's ID to `createVercelAdapter`: +Project Connections let your project read flags from another project in the same team without an SDK key. With the Flags SDK, use `@flags-sdk/vercel` version 1.6.0 or later. In the source project's **Flags → Connections** page, grant your project access. Then pass the source project's ID to `createVercelAdapter`: ```ts title="flags.ts" import { flag } from 'flags/next'; @@ -167,7 +167,9 @@ The adapter uses your project's OIDC token. Keep `vercelAdapter` for flags owned Connections grant read access across environments. Your deployment's token selects the source environment: production reads production, preview reads preview, and local development reads development. Custom environments use preview. The `projectId` option cannot be combined with an SDK key. -See [Project Connections](https://vercel.com/docs/flags/vercel-flags/project-connections) for permissions and connection management. +If you use the [core library](https://vercel.com/docs/flags/vercel-flags/sdks/core) directly, use `@vercel/flags-core` version 1.11.0 or later. The adapter includes the required core library version. + +Managing connections with `vercel flags connections` requires Vercel CLI version 63.0.0 or later. See [Project Connections](https://vercel.com/docs/flags/vercel-flags/project-connections) for permissions and connection management. ### SDK keys diff --git a/skills/flags-sdk/SKILL.md b/skills/flags-sdk/SKILL.md index 6ff02e55..ca0a0890 100644 --- a/skills/flags-sdk/SKILL.md +++ b/skills/flags-sdk/SKILL.md @@ -2,8 +2,8 @@ name: flags-sdk description: > Implement feature flags in Next.js or SvelteKit code with the Flags SDK (`flags` npm package). - Use when installing or configuring the SDK, declaring flags with `flag()`, wiring a provider - adapter (`@flags-sdk/vercel`, Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, + Use when installing or configuring the SDK, declaring flags with `flag()`, setting up Project + Connections, wiring a provider adapter (`@flags-sdk/vercel`, Statsig, LaunchDarkly, PostHog, GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom), using `identify`, `dedupe`, or `evaluate`, keeping pages static with precompute, setting up Flags Explorer and the Vercel Toolbar, or encrypting flag values. Triggers: `flags/next`, `flags/sveltekit`, `flags/react`, @@ -174,7 +174,7 @@ Use this flow when the flag was created in the dashboard or by someone else, for ## Vercel Flags adapter -`@flags-sdk/vercel` connects `flag()` declarations to Vercel Flags. `vercelAdapter` authenticates with the project's Vercel OIDC token and evaluates the configuration of the current environment. Use `createVercelAdapter({ projectId })` for a connected same-team project's flags; see [Project Connections](references/providers.md#project-connections). SDK keys (`FLAGS`) are for manual authentication, such as apps outside Vercel or selecting an environment explicitly. Activating Vercel Flags creates a `FLAGS_SECRET` per environment for Flags Explorer. +`@flags-sdk/vercel` connects `flag()` declarations to Vercel Flags. `vercelAdapter` authenticates with the project's Vercel OIDC token and evaluates the configuration of the current environment. Use `@flags-sdk/vercel` version 1.6.0 or later and `createVercelAdapter({ projectId })` for a connected same-team project's flags; see [Project Connections](references/providers.md#project-connections). SDK keys (`FLAGS`) are for manual authentication, such as apps outside Vercel or selecting an environment explicitly. Activating Vercel Flags creates a `FLAGS_SECRET` per environment for Flags Explorer. For user targeting, attribute types, custom adapter configuration, sharing a `@vercel/flags-core` client, and the Flags Explorer endpoint, see [references/providers.md — Vercel](references/providers.md#vercel). diff --git a/skills/flags-sdk/references/providers.md b/skills/flags-sdk/references/providers.md index c79b5c17..1423517c 100644 --- a/skills/flags-sdk/references/providers.md +++ b/skills/flags-sdk/references/providers.md @@ -100,6 +100,8 @@ export const GET = createFlagsDiscoveryEndpoint(async () => { ### Project Connections +Check the installed `@flags-sdk/vercel` version before changing the code. Project Connections require version 1.6.0 or later; upgrade it if needed. The adapter includes the required core library version. + To read flags from another project in the same team, first grant the consumer project access from the source project's **Flags → Connections** page. Then pass the source project's ID: ```ts @@ -117,7 +119,7 @@ export const sharedFeature = flag({ Use `vercelAdapter` alongside this adapter for the consumer's own flags. Both use the consumer's OIDC token; do not mint an SDK key for a connection. Run `vercel env pull` in the consumer project for local development. Connections apply across environments, and the token selects the source environment; custom environments use preview. -For direct core access, use `createClient({ projectId: 'prj_source' })`. The `projectId` option cannot be combined with an SDK key. See [Project Connections](https://vercel.com/docs/flags/vercel-flags/project-connections) for permissions and setup. +For direct core access, use `@vercel/flags-core` version 1.11.0 or later with `createClient({ projectId: 'prj_source' })`. The `projectId` option cannot be combined with an SDK key. CLI management requires Vercel CLI version 63.0.0 or later; use the `vercel-flags` skill for the connection workflow, or see the [CLI reference](https://vercel.com/docs/cli/flags#project-connections). See [Project Connections](https://vercel.com/docs/flags/vercel-flags/project-connections) for permissions and setup. ### Custom configuration diff --git a/skills/vercel-flags/SKILL.md b/skills/vercel-flags/SKILL.md index 0252183d..b447fc96 100644 --- a/skills/vercel-flags/SKILL.md +++ b/skills/vercel-flags/SKILL.md @@ -6,7 +6,7 @@ description: > experiment, percentage rollout, or targeting rule, or wants to gate or hide a feature for some users, even before a library or provider is chosen. Covers choosing an integration (Flags SDK, `@vercel/flags-core`, OpenFeature), the Vercel dashboard, the `vercel flags` CLI (create, inspect, - set, split, rollout, rules, segments, evaluations, archive), OIDC vs SDK keys, `FLAGS_SECRET`, and + set, split, rollout, rules, segments, evaluations, archive, connections), Project Connections, OIDC vs SDK keys, `FLAGS_SECRET`, and Flags Explorer overrides. For `flag()` declarations, adapters, precompute, and the Flags Explorer endpoint in Next.js or SvelteKit code, load the `flags-sdk` skill. --- @@ -24,6 +24,7 @@ Use this skill to decide how a feature should be flagged, to create and change f - **Planning** ("put this behind a flag", "roll this out to 10%", "A/B test the pricing page", "add a kill switch"): follow [Plan a flag](#plan-a-flag), then [Choose an approach](#choose-an-approach). - **Create or manage a flag with no code change** (create, inspect, enable, set, split, rollout, rules, archive): follow [Manage flags with the CLI](#manage-flags-with-the-cli). This needs an authenticated CLI, not SDK packages, Toolbar, Flags Explorer, or `.env.local` (except `vercel flags override`, which reads `FLAGS_SECRET`). +- **Share flags between projects**: follow [Project Connections](references/cli.md#project-connections) to connect projects in the same team, then configure the consumer application. - **Clean up or remove a flag** ("remove this flag", "clean up stale flags", "inline this flag"): follow [references/cleanup.md](references/cleanup.md), then [Lifecycle and safety](references/cli.md#lifecycle-and-safety) before archiving. - **Add a flag to an app that already uses the Flags SDK** (`flags` in `package.json`): load the `flags-sdk` skill right away; it creates the flag on Vercel and declares it in code. - **Implement in code otherwise**: follow [Choose an approach](#choose-an-approach) and load the matching skill or reference. Inside an app repository, treat an ambiguous request as plan, create, and implement. @@ -82,7 +83,8 @@ Always `inspect` first so you know what each environment serves today, and match ## Credentials - **OIDC**: on Vercel, the app authenticates with the project's OIDC token and evaluates the configuration of the current environment. `vercel env pull` writes the Development token to `.env.local` for local development ([Getting started](https://vercel.com/docs/flags/vercel-flags/quickstart#pull-local-openid-connect-credentials)). -- **SDK keys (`FLAGS`)**: only for apps outside Vercel, custom environments, or flags owned by another project. Each key is scoped to one environment and shown once, at creation ([SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)). Not a recovery path for failed CLI authentication. +- **Project Connections**: read another same-team project's flags with the consumer project's OIDC token, without an SDK key. Follow [Project Connections](references/cli.md#project-connections) for setup and minimum versions. +- **SDK keys (`FLAGS`)**: for apps outside Vercel, selecting an environment explicitly, or reading flags across teams. Each key is scoped to one environment and shown once, at creation ([SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)). Not a recovery path for failed CLI authentication. - **`FLAGS_SECRET`**: created per environment when Vercel Flags is activated for a project. It signs Flags Explorer overrides and precompute codes, and `vercel flags override` reads it from the environment or `.env.local`. Preserve existing values and never rotate them as part of routine setup; a missing local value does not mean the remote value is missing, so check the target environment before generating one. The `flags-sdk` skill documents how to generate a missing value. Do not print secrets to the terminal, logs, or chat. ## Flags Explorer diff --git a/skills/vercel-flags/references/cli.md b/skills/vercel-flags/references/cli.md index 3ad1a33e..d277dce7 100644 --- a/skills/vercel-flags/references/cli.md +++ b/skills/vercel-flags/references/cli.md @@ -13,10 +13,18 @@ For the current subcommand list and options, run `vercel flags --help` or `verce - **Targeting attributes**: `split`, `rollout`, and `rules add` take `--by .` (and `--condition .::`). Define the entity and attribute under Flags → Entities first, and return the same names from the app's evaluation context; the docs use a `User` entity with an `id` attribute and `--by user.id` ([Roll out a feature](https://vercel.com/docs/flags/vercel-flags/cli/roll-out-feature), [Entities](https://vercel.com/docs/flags/vercel-flags/dashboard/entities)). When the attribute is missing from the context, a split or rollout serves its fallback variant (`--default-variant` in the CLI) and a rule that references it is skipped. Verify with `evaluations`. - **Attribute types**: each attribute is a String, Number, Boolean, String Array, or Timestamp, and the app must send a matching value ([Entities](https://vercel.com/docs/flags/vercel-flags/dashboard/entities)). Timestamp is a Unix epoch in milliseconds as a number. How to return each type from `identify()`, including a deduped `Date.now()` for release-at-a-time rules, is in the `flags-sdk` skill's provider reference (Attribute types). - **Timestamp conditions**: for Timestamp attributes, `--condition` accepts `gt`, `lt`, `gte`, `lte` or the aliases `after`, `before`, `at-or-after`, `at-or-before` with an ISO 8601 date-time or epoch milliseconds, for example `--condition system.time:at-or-after:2026-04-16T09:00:00Z`. `after` and `before` are exclusive; other operators are rejected. A date-time without a timezone uses the machine's local timezone, so include `Z` or an offset. `--by` rejects Timestamp attributes. -- **Authentication**: on Vercel, the app authenticates with the project's OIDC token and uses the configuration of the current environment; `vercel env pull` brings that credential to `.env.local` for local development. SDK keys (`FLAGS`) are for manual authentication: apps outside Vercel, custom environments, or flags owned by another project. Each SDK key is scoped to one environment and its full value is shown once, at creation ([Getting started](https://vercel.com/docs/flags/vercel-flags/quickstart#pull-local-openid-connect-credentials), [SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)). +- **Authentication**: on Vercel, the app authenticates with the project's OIDC token and uses the configuration of the current environment; `vercel env pull` brings that credential to `.env.local` for local development. For another same-team project's flags, use [Project Connections](#project-connections) with the consumer project's OIDC token. SDK keys (`FLAGS`) are for manual authentication: apps outside Vercel, selecting an environment explicitly, or reading flags across teams. Each SDK key is scoped to one environment and its full value is shown once, at creation ([Getting started](https://vercel.com/docs/flags/vercel-flags/quickstart#pull-local-openid-connect-credentials), [SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)). - **Overrides**: Flags Explorer stores overrides in a cookie signed with `FLAGS_SECRET`; flags declared with the Flags SDK honour it automatically ([Handling overrides](https://vercel.com/docs/flags/flags-explorer/getting-started#handling-overrides)). `vercel flags override =` produces the same token for the `vercel-flag-overrides` cookie and reads `FLAGS_SECRET` from the environment or `.env.local`, so use the secret of the environment you test against (see [Credentials](../SKILL.md#credentials)). - **Embedded definitions**: Vercel builds fetch the flag definitions once and bundle them into the deployment when the project uses `@flags-sdk/vercel` or `@vercel/flags-core` and the build can authenticate. This keeps every function on one snapshot and serves as the runtime fallback when the service is unreachable; opt out with `VERCEL_FLAGS_DISABLE_DEFINITION_EMBEDDING=1` ([Embedded definitions](https://vercel.com/docs/flags/vercel-flags/sdks/core#embedded-definitions)). `vercel flags prepare` is the same step for builds that run outside Vercel. +## Project Connections + +Connections grant a consumer project read access to a source project's flags within the same team. Use Vercel CLI 63.0.0 or later. Run `vercel flags connections --help` for commands and options, even if connections are absent from the top-level help in an older release. + +Confirm the source project, consumer project, and team before creating a connection. Reuse an existing connection. Creation requires team Member or Owner access, or Project Admin access on the source project, plus permission to view the consumer project. See [required permissions](https://vercel.com/docs/flags/vercel-flags/project-connections#required-permissions). + +Configure the consumer with `@flags-sdk/vercel` 1.6.0 or later and `createVercelAdapter({ projectId: 'prj_source' })`, or `@vercel/flags-core` 1.11.0 or later and `createClient({ projectId: 'prj_source' })`. Replace `prj_source` with the source project's ID. Follow [the SDK connection example](https://flags-sdk.dev/docs/providers/vercel) or the [core guide](https://vercel.com/docs/flags/vercel-flags/sdks/core). Do not create an SDK key for a connection; link to the consumer project and run `vercel env pull` for local OIDC credentials. The consumer's token selects the source environment, with custom environments mapped to preview. + ## Lifecycle and safety The docs describe these flows end to end: [Roll out a feature](https://vercel.com/docs/flags/vercel-flags/cli/roll-out-feature), [Run an A/B test](https://vercel.com/docs/flags/vercel-flags/cli/run-ab-test). For cleanup, follow the deployment and evaluation checks below before archiving.