From f9a4874acb6a4defbca0d7c88032f739546c586c Mon Sep 17 00:00:00 2001 From: Akshit Sinha Date: Thu, 29 Oct 2026 15:02:48 +0530 Subject: [PATCH] [Flagship] Document the local flag store for wrangler dev --- .../flagship/2026-11-02-local-flag-store.mdx | 21 +++++ src/content/docs/cf/projects/index.mdx | 6 +- src/content/docs/flagship/configuration.mdx | 82 ++++++++++++++++++- src/content/docs/flagship/get-started.mdx | 14 ++++ src/content/docs/flagship/index.mdx | 2 + .../flagship/reference/wrangler-commands.mdx | 25 +++++- .../workers/local-development/local-data.mdx | 20 +++++ .../workers/wrangler/commands/flagship.mdx | 8 ++ .../docs/workers/wrangler/configuration.mdx | 33 ++++++++ .../partials/workers/bindings_per_env.mdx | 2 + 10 files changed, 210 insertions(+), 3 deletions(-) create mode 100644 src/content/changelog/flagship/2026-11-02-local-flag-store.mdx diff --git a/src/content/changelog/flagship/2026-11-02-local-flag-store.mdx b/src/content/changelog/flagship/2026-11-02-local-flag-store.mdx new file mode 100644 index 00000000000..5df36c3c8f8 --- /dev/null +++ b/src/content/changelog/flagship/2026-11-02-local-flag-store.mdx @@ -0,0 +1,21 @@ +--- +title: Evaluate Flagship flags locally +description: Flagship bindings now evaluate flags against a local flag store during local development, so you can develop offline and test flag changes without touching your remote app. +products: + - flagship +date: 2026-11-02 +--- + +[Flagship](/flagship/) bindings now evaluate flags against a local flag store during local development, instead of calling your remote app. You can develop offline and test flag changes without affecting production. This applies to [`wrangler dev`](/workers/wrangler/commands/general/#dev), the [Cloudflare Vite plugin](/workers/vite-plugin/), the [Vitest integration](/workers/testing/vitest-integration/), and [`cf dev`](/cf/projects/#start-development). + +The local store starts empty, so evaluations return the default value you pass in code. Add and manage local flags in any of these ways: + +- **Wrangler** — Add `--local` to `wrangler flagship flags` commands, such as `create`, `update`, and `evaluate`. To copy all flags from your remote app, run `npx wrangler flagship flags pull `. +- **Local Explorer** — Create, edit, toggle, and evaluate flags in [Local Explorer](/workers/local-development/local-explorer/) while your dev server runs. +- **`cf` CLI** — Add `--local` to [`cf flagship` commands](/flagship/configuration/#use-the-cf-cli). + +To keep evaluating against your remote app instead, set [`remote: true`](/flagship/configuration/#use-the-remote-app-instead) on the binding. + +The local flag store requires Wrangler v4.135.0 or `@cloudflare/vite-plugin` v1.56.0 or later. Flagship in Local Explorer requires Wrangler v4.148.0 or `@cloudflare/vite-plugin` v1.63.0 or later. + +Refer to [Flagship local development](/flagship/configuration/#local-development) for details. diff --git a/src/content/docs/cf/projects/index.mdx b/src/content/docs/cf/projects/index.mdx index f292ccbc546..bab53436523 100644 --- a/src/content/docs/cf/projects/index.mdx +++ b/src/content/docs/cf/projects/index.mdx @@ -373,7 +373,11 @@ needs to be running. Local support covers these commands: - `cf d1 migrations list` and `cf d1 migrations apply` - `cf r2 objects get`, `cf r2 objects put`, `cf r2 objects list`, and `cf r2 objects bulk-delete` -- `cf d1 list`, `cf kv namespaces list`, and `cf r2 buckets list` +- `cf flagship apps flags list`, `get`, `create`, `update`, `patch`, `delete`, + and `evaluate` +- `cf flagship apps evaluate get` +- `cf d1 list`, `cf kv namespaces list`, `cf flagship apps list`, and + `cf r2 buckets list` `cf d1 query` has no local equivalent. Use `cf d1 raw` instead. A command without a local equivalent fails with diff --git a/src/content/docs/flagship/configuration.mdx b/src/content/docs/flagship/configuration.mdx index 9cba6bf7b67..670c3f9d949 100644 --- a/src/content/docs/flagship/configuration.mdx +++ b/src/content/docs/flagship/configuration.mdx @@ -93,4 +93,84 @@ Refer to the [binding API reference](/flagship/binding/) for the full list of me ## Local development -Flagship bindings work with `wrangler dev`. Local Workers use the live Flagship app configured by `app_id`. There is no local flag store. Make sure your local Wrangler configuration points to a valid Flagship app before testing evaluations. +During local development, Flagship bindings use a local flag store by default. This applies to [`wrangler dev`](/workers/wrangler/commands/general/#dev), the [Cloudflare Vite plugin](/workers/vite-plugin/), the [Vitest integration](/workers/testing/vitest-integration/), and [`cf dev`](/cf/projects/#start-development). The store starts empty, so evaluations return the default value you pass at the call site until you add flags. + +This is the default behavior in Wrangler v4.135.0 and later, and in `@cloudflare/vite-plugin` v1.56.0 and later. + +### Copy flags from your remote app + +To copy flags from your remote app into the local store: + +```sh +npx wrangler flagship flags pull +``` + +`pull` also seeds the account tag used for [percentage rollout](/flagship/targeting/percentage-rollouts/) bucketing, so local buckets match the remote app. Flags that exist only in the local store are left untouched. + +Flags are not pulled automatically, so `wrangler dev` works offline and never overwrites flags you changed locally. + +`pull` writes to the default local store in `.wrangler/state`. If your dev server keeps its data in a different directory, pass `--persist-to ` so that `pull` writes to the same place. For example, the Cloudflare Vite plugin 2.0 beta keeps its data in `.cloudflare/state`: + +```sh +npx wrangler flagship flags pull --persist-to .cloudflare/state +``` + +### Manage the local store + +To create or change flags without affecting the remote app, pass `--local` to the flag commands: + +```sh +npx wrangler flagship flags create new-checkout --local +npx wrangler flagship flags list --local +``` + +Flag commands still default to the remote app. You cannot pass `--local` and `--remote` together. + +You can also inspect and edit the local store in [Local Explorer](/workers/local-development/local-explorer/). Flagship apps appear in Local Explorer in Wrangler v4.148.0 and later, and in `@cloudflare/vite-plugin` v1.63.0 and later. + +### Use the remote app instead + +To evaluate against the remote app during local development, set `remote` to `true` on the binding: + + + +```jsonc +{ + "flagship": [ + { + "binding": "FLAGS", + "app_id": "", + "remote": true, + }, + ], +} +``` + + + +### Use the cf CLI + +[`cf dev`](/cf/projects/#start-development) uses the local flag store, the same as `wrangler dev`. + +To manage local flags with `cf`, add `--local` to a supported `cf flagship` command. No dev server needs to be running, and the app does not need to be bound to a Worker. + +```sh +cf flagship apps flags list --app-id --local +cf flagship apps flags get --app-id --local +``` + +These commands support `--local`: + +- `cf flagship apps list` +- `cf flagship apps flags list`, `get`, `create`, `update`, `patch`, `delete`, and `evaluate` +- `cf flagship apps evaluate get` + +Other `cf flagship` commands, such as `cf flagship apps get`, `cf flagship apps definitions get`, and `cf flagship apps flags changelog`, fail with `This command has no local equivalent.` Run them without `--local` to use the remote app. + +By default, `cf` keeps [local data in its own directory](/cf/projects/#local-resource-data), which `wrangler dev` and the Cloudflare Vite plugin do not read. To work on the same flags as your dev server, pass its data directory. This is `.wrangler/state` for `wrangler dev` and the Cloudflare Vite plugin 1.x, and `.cloudflare/state` for the Vite plugin 2.0 beta: + +```sh +cf flagship apps flags list --app-id --local --persist-to .wrangler/state +``` + +`cf` cannot copy flags from your remote app. Use `npx wrangler flagship flags pull ` instead, with the same `--persist-to` value if you set one. diff --git a/src/content/docs/flagship/get-started.mdx b/src/content/docs/flagship/get-started.mdx index 83a2a448950..5f5ba6a86a5 100644 --- a/src/content/docs/flagship/get-started.mdx +++ b/src/content/docs/flagship/get-started.mdx @@ -83,6 +83,19 @@ export default { The third argument to `getBooleanValue` is the [evaluation context](/flagship/concepts/#evaluation-context). Flagship uses the context attributes to match targeting rules. In this example, the `userId` attribute is passed so that percentage rollouts and user-specific targeting work correctly. +## Test locally + +Copy the flag into the local store, then start a local session: + +```sh +npx wrangler flagship flags pull +npx wrangler dev +``` + +To use the [Cloudflare Vite plugin](/workers/vite-plugin/) instead, start your Vite dev server. In a [`cf`](/cf/) project, run `cf dev`, and add `--persist-to .cloudflare/state` to the `pull` command. Either way, run the Wrangler `pull` command first, because `cf` cannot pull flags. + +Without `pull`, the local store is empty, so evaluations return the default value you pass in code. For other ways to manage local flags, and to use your remote app instead, refer to [Local development](/flagship/configuration/#local-development). + ## Deploy and test Deploy your Worker: @@ -180,6 +193,7 @@ Refer to the [SDK documentation](/flagship/sdk/) for detailed setup instructions ## Next steps - Manage flags from the command line with the [`wrangler flagship` commands](/flagship/reference/wrangler-commands/). +- Test against a [local flag store](/flagship/configuration/#local-development) with Wrangler, the Vite plugin, or `cf dev`. - Learn about [targeting rules](/flagship/targeting/) to serve different values based on user attributes. - Explore the full [binding API reference](/flagship/binding/) for all evaluation methods. - Read about [percentage rollouts](/flagship/targeting/percentage-rollouts/) for gradual feature releases. diff --git a/src/content/docs/flagship/index.mdx b/src/content/docs/flagship/index.mdx index c1bad660777..7a5deb70bc7 100644 --- a/src/content/docs/flagship/index.mdx +++ b/src/content/docs/flagship/index.mdx @@ -4,6 +4,8 @@ description: Ship features safely with Flagship, Cloudflare's feature flag servi pcx_content_type: overview sidebar: order: 1 + badge: + text: Beta head: - tag: title content: Overview diff --git a/src/content/docs/flagship/reference/wrangler-commands.mdx b/src/content/docs/flagship/reference/wrangler-commands.mdx index b6b7de3c555..561eb37e92f 100644 --- a/src/content/docs/flagship/reference/wrangler-commands.mdx +++ b/src/content/docs/flagship/reference/wrangler-commands.mdx @@ -16,7 +16,7 @@ Use `wrangler flagship` to manage Flagship apps and feature flags from the comma ### Authenticate Wrangler -`wrangler flagship` calls the Cloudflare API. Authenticate Wrangler before running commands: +Commands that target the remote app call the Cloudflare API. Authenticate Wrangler before running them: ```sh wrangler login @@ -51,6 +51,29 @@ This binding is only used by your Worker's runtime code (`env.FLAGS`). `wrangler +## Local flag store + +[`wrangler dev`](/workers/wrangler/commands/general/#dev), the [Cloudflare Vite plugin](/workers/vite-plugin/), and [`cf dev`](/cf/projects/#start-development) evaluate Flagship bindings against a local flag store. The store starts empty and is not filled automatically. + +Copy flags from the remote app into that store: + +```sh +wrangler flagship flags pull +``` + +`pull` requires authentication because it reads the remote app. Matching keys are overwritten. Flags that exist only locally are reported, not deleted. `pull` writes to the default local store in `.wrangler/state`; pass `--persist-to ` if your dev server keeps its data elsewhere. + +`create`, `get`, `list`, `update`, `delete`, `enable`, `disable`, `set`, `rollout`, `split`, `evaluate`, and the `rules` commands accept `--local` to read and write the local store. They still default to the remote app. + +```sh +wrangler flagship flags list --local +wrangler flagship flags create new-checkout --local +``` + +You cannot pass `--local` and `--remote` together. `--persist-to` requires `--local`. + +For binding configuration, including `remote: true`, and for managing the local store with the `cf` CLI, refer to [Local development](/flagship/configuration/#local-development). + ## Quick start Create a boolean flag, evaluate it for a user, and disable it as a kill switch: diff --git a/src/content/docs/workers/local-development/local-data.mdx b/src/content/docs/workers/local-development/local-data.mdx index 770a9cbc9b7..62b475689be 100644 --- a/src/content/docs/workers/local-development/local-data.mdx +++ b/src/content/docs/workers/local-development/local-data.mdx @@ -79,6 +79,26 @@ You may also include [other metadata](/workers/wrangler/commands/r2/#r2-object-p args="d1 execute --file=./schema.sql --local" /> +### Flagship apps + +#### [Copy flags from a remote app](/flagship/configuration/#local-development) + + + +#### [Create a flag in the local store](/flagship/reference/wrangler-commands/#local-flag-store) + + + +To manage the local store with the `cf` CLI instead, refer to [Flagship local development](/flagship/configuration/#use-the-cf-cli). + ### Durable Objects For Durable Objects, unlike KV, D1, and R2, there are no CLI commands to populate them with local data. To add data to Durable Objects during local development, you must write application code that creates Durable Object instances and [calls methods on them that store state](/durable-objects/best-practices/access-durable-objects-storage/). This typically involves creating development endpoints or test routes that initialize your Durable Objects with the desired data. diff --git a/src/content/docs/workers/wrangler/commands/flagship.mdx b/src/content/docs/workers/wrangler/commands/flagship.mdx index 54e103f7c50..7bfb6c96042 100644 --- a/src/content/docs/workers/wrangler/commands/flagship.mdx +++ b/src/content/docs/workers/wrangler/commands/flagship.mdx @@ -12,6 +12,14 @@ Use `wrangler flagship` to manage [Flagship](/flagship/) apps and feature flags `wrangler flagship` is available in Wrangler v4.107.0 and later. +:::note[`--local` option] +Most `wrangler flagship flags` commands accept `--local` to read and write the local flag store used by [`wrangler dev`](/workers/wrangler/commands/general/#dev), the [Cloudflare Vite plugin](/workers/vite-plugin/), and [`cf dev`](/cf/projects/#start-development). They still default to the remote app. Bindings with `remote: true` do not use the local store, so `--local` changes do not affect them. + +`wrangler flagship flags pull ` copies remote flags into that store. + +For more information, refer to [Flagship local development](/flagship/configuration/#local-development). +::: + ## Authentication Run `wrangler login`, or set [`CLOUDFLARE_API_TOKEN`](/workers/wrangler/system-environment-variables/) to an API token with Flagship permissions. diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index f8dd2f0bba2..dc39870ae73 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -259,6 +259,9 @@ Non-inheritable keys are configurable at the top-level, but cannot be inherited - `secrets_store_secrets` - A list of Secrets Store bindings that your worker should be bound to. Refer to [Secrets Store](/secrets-store/). +- `flagship` + - A list of Flagship apps that your Worker should be bound to. Refer to [Flagship](#flagship). + ## Types of routes There are three types of [routes](/workers/configuration/routing/): [Custom Domains](/workers/configuration/routing/custom-domains/), [routes](/workers/configuration/routing/routes/), and [`workers.dev`](/workers/configuration/routing/workers-dev/). @@ -768,6 +771,36 @@ Example: +### Flagship + +[Flagship](/flagship/) is Cloudflare's feature flag service. Bind a Flagship app to evaluate flags from your Worker. + +- `binding` + - The binding name used to refer to the Flagship app. The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). + +- `app_id` + - The ID of the Flagship app. + +- `remote` + - During local development, Flagship bindings use a [local flag store](/flagship/configuration/#local-development) by default. Set `remote` to `true` to evaluate against the remote app instead. + +Example: + + + +```jsonc +{ + "flagship": [ + { + "binding": "FLAGS", + "app_id": "", + }, + ], +} +``` + + + ### Hyperdrive [Hyperdrive](/hyperdrive/) bindings allow you to interact with and query any Postgres database from within a Worker. diff --git a/src/content/partials/workers/bindings_per_env.mdx b/src/content/partials/workers/bindings_per_env.mdx index ec5d24e8e78..9228716e9b4 100644 --- a/src/content/partials/workers/bindings_per_env.mdx +++ b/src/content/partials/workers/bindings_per_env.mdx @@ -18,6 +18,7 @@ | **Durable Objects** | ✅ | ❌ [^1] | | **Containers** | ✅ | ❌ | | **Email Bindings** | ✅ | ✅ | +| **Flagship** | ✅ | ✅ | | **Hyperdrive** | ✅ | ❌ | | **Images** | ✅ | ✅ | | **KV** | ✅ | ✅ | @@ -48,6 +49,7 @@ Supported only in [`wrangler dev --remote`](/workers/wrangler/commands/general/# | **Durable Objects** | ✅ | | **Containers** | ❌ | | **Email Bindings** | ✅ | +| **Flagship** | ✅ | | **Hyperdrive** | ✅ | | **Images** | ✅ | | **KV** | ✅ |