diff --git a/src/content/changelog/flagship/2026-08-28-local-flag-store.mdx b/src/content/changelog/flagship/2026-08-28-local-flag-store.mdx new file mode 100644 index 00000000000..b84fd71885d --- /dev/null +++ b/src/content/changelog/flagship/2026-08-28-local-flag-store.mdx @@ -0,0 +1,29 @@ +--- +title: Evaluate Flagship flags locally in wrangler dev +description: Flagship bindings now use a local flag store during wrangler dev, so local development works offline and does not change production flags. +products: + - flagship +date: 2026-08-28 +--- + +**[Wrangler](/workers/wrangler/)** now evaluates [Flagship](/flagship/) bindings against a local flag store during [`wrangler dev`](/workers/wrangler/commands/general/#dev). The store starts empty, so flags fall back to the default you pass at the call site until you populate it. + +Copy flags from your remote app: + +```sh +npx wrangler flagship flags pull +``` + +`create`, `get`, `list`, `update`, `delete`, `enable`, `disable`, `set`, `rollout`, `split`, `evaluate`, and the `rules` commands accept `--local` to read and write that store. They still default to the remote app. + +To keep using the remote app during local development, set `remote: true` on the binding: + +```jsonc +{ + "flagship": [{ "binding": "FLAGS", "app_id": "my-app", "remote": true }], +} +``` + +When [Local Explorer](/workers/local-development/local-explorer/) is open, bound Flagship apps appear in the sidebar. You can list, create, edit, toggle, and evaluate flags against the same local store. + +Refer to [Flagship local development](/flagship/configuration/#local-development) for details. diff --git a/src/content/docs/flagship/configuration.mdx b/src/content/docs/flagship/configuration.mdx index 9cba6bf7b67..800eee595a5 100644 --- a/src/content/docs/flagship/configuration.mdx +++ b/src/content/docs/flagship/configuration.mdx @@ -93,4 +93,41 @@ 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 [`wrangler dev`](/workers/wrangler/commands/general/#dev), Flagship bindings use a local flag store by default. The store starts empty, so evaluations return the default value you pass at the call site until you add flags. + +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. + +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. + +To evaluate against the remote app during local development, set `remote` to `true` on the binding: + + + +```jsonc +{ + "flagship": [ + { + "binding": "FLAGS", + "app_id": "", + "remote": true, + }, + ], +} +``` + + + +You can also inspect and edit the local store in [Local Explorer](/workers/local-development/local-explorer/). diff --git a/src/content/docs/flagship/get-started.mdx b/src/content/docs/flagship/get-started.mdx index c52c93db7f4..40c148fdd25 100644 --- a/src/content/docs/flagship/get-started.mdx +++ b/src/content/docs/flagship/get-started.mdx @@ -83,6 +83,17 @@ 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 +``` + +Without `pull`, the local store is empty and evaluations return the default you pass in code. Refer to [Local development](/flagship/configuration/#local-development) for `--local` flag commands and `remote: true`. + ## Deploy and test Deploy your Worker: @@ -180,6 +191,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) during `wrangler 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/reference/wrangler-commands.mdx b/src/content/docs/flagship/reference/wrangler-commands.mdx index fb59a5ba82c..b71030f3ef9 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) evaluates Flagship bindings against a local flag store. The store starts empty. + +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. + +`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`, 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..c46ba913162 100644 --- a/src/content/docs/workers/local-development/local-data.mdx +++ b/src/content/docs/workers/local-development/local-data.mdx @@ -79,6 +79,24 @@ 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) + + + ### 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/local-development/local-explorer.mdx b/src/content/docs/workers/local-development/local-explorer.mdx index d3b0558c52f..d3f9f70350b 100644 --- a/src/content/docs/workers/local-development/local-explorer.mdx +++ b/src/content/docs/workers/local-development/local-explorer.mdx @@ -46,6 +46,7 @@ Local Explorer supports the following binding types: | [D1](/d1/) | Browse tables and rows, run SQL queries | Insert, update, and delete rows through SQL | | [Durable Objects](/durable-objects/) (SQLite storage) | Browse SQLite tables and rows, run SQL queries | Insert, update, and delete rows through SQL | | [Workflows](/workflows/) | List instances, view status and step history | Trigger new runs, retry failed instances | +| [Flagship](/flagship/) | List flags, view variants and targeting rules | Create, edit, toggle, delete, and evaluate flags | ### D1 and Durable Objects SQL Studio diff --git a/src/content/docs/workers/wrangler/commands/flagship.mdx b/src/content/docs/workers/wrangler/commands/flagship.mdx index 54e103f7c50..f79a34866ec 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). They still default to the remote app. + +`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 8f863c4f470..771c504b070 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/). @@ -749,6 +752,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 f959de2811f..a705f2f6c39 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** | ✅ |