--- title: "Feature flags" description: "Define typed Beignet feature flags, evaluate them through FlagsPort, test them with memory adapters, and adapt OpenFeature providers." url: "https://www.beignetjs.com/feature-flags" markdown_url: "https://www.beignetjs.com/markdown/feature-flags.md" framework_version: "0.0.65" documentation_scope: "current-checkout" source_revision: "ba3f49c103f3c4515e8ca14e07651fe5b83e2cec" source_modified: true --- # Feature flags Feature flags let production apps ship changes behind typed runtime decisions without coupling use cases to a vendor SDK. Beignet owns the flag definitions and `FlagsPort`; providers decide where evaluation happens. The API follows OpenFeature's core semantics — typed values, targeting context, defaults, evaluation details, and tracking — while keeping imports and tests in Beignet's port/provider model. ## Define flags Declare flags in the feature that owns the behavior: ```typescript // features/billing/flags.ts import { defineFlag, defineFlags } from "@beignet/core/flags"; export const billingFlags = defineFlags({ newCheckout: defineFlag.boolean("billing.new-checkout", { default: false, description: "Route checkout creation through the new billing flow.", }), pricingCopy: defineFlag.string("billing.pricing-copy", { default: "control", }), }); ``` String and number flags widen to `string` and `number` by default. Pass a generic when the app wants a closed set of variants, such as `defineFlag.string<"control" | "treatment">(...)`. ## Evaluate in application code Use cases evaluate flags through `ctx.ports.flags`. Provider failures return the flag default instead of throwing into product workflows; call `details(...)` when you need the reason, variant, metadata, or error summary. ```typescript const enabled = await ctx.ports.flags.evaluate(billingFlags.newCheckout, { context: { targetingKey: requireUserId(ctx), subject: { type: "user", id: requireUserId(ctx) }, tenant: ctx.tenant, attributes: { plan: account.plan }, privateAttributes: ["email"], requestId: ctx.requestId, traceId: ctx.traceId, }, }); ``` OpenFeature receives `attributes` unchanged unless Beignet has an authoritative value for the same reserved key. For example, `tenant.id` replaces an `attributes.tenantId` value, while `attributes.tenantId` remains available when the evaluation context has no tenant. Plain evaluation does not record exposure. Record exposure explicitly when the user actually sees or can be affected by the flagged behavior: ```typescript await ctx.ports.flags.recordExposure(billingFlags.newCheckout, { context: flagContext, value: enabled, }); ``` ## Setup with OpenFeature Use the OpenFeature provider to adapt LaunchDarkly, Statsig, Unleash, flagd, or any other OpenFeature-compatible provider behind Beignet's `FlagsPort`: ```bash bun add @beignet/provider-flags-openfeature @openfeature/server-sdk ``` ```typescript import { createNextServer, createNextServerLoader } from "@beignet/next"; import { createOpenFeatureFlagsProvider } from "@beignet/provider-flags-openfeature"; import { initialPorts } from "@/infra/port-wiring"; import { openFeatureProvider } from "@/infra/flags/openfeature"; export const getServer = createNextServerLoader(() => createNextServer({ ports: initialPorts, providers: [ createOpenFeatureFlagsProvider({ provider: openFeatureProvider, domain: "app", }), ], context: appContextBlueprint, }), ); ``` The provider contributes `ctx.ports.flags` and `ctx.ports.openFeature` as an escape hatch for advanced OpenFeature operations. When the app already owns an OpenFeature client, pass `client`; Beignet uses it without registering the optional `provider` on OpenFeature's process-global API. Shutdown leaves bindings alone by default. `restoreOnStop: true` restores only the effective provider previously bound to this domain, and only while the binding is still owned by this Beignet provider. It never clears providers registered by other application components. ## Testing Use `createMemoryFlags(...)` or `createStaticFlags(...)` for tests: ```typescript import { createMemoryFlags } from "@beignet/core/flags"; import { billingFlags } from "@/features/billing/flags"; const flags = createMemoryFlags(); flags.set(billingFlags.newCheckout, true); ``` `createTestPorts(...)` includes an in-memory `flags` port by default, so most use-case tests only need to override the flag values they exercise. ## Devtools When devtools are installed before a flags provider, evaluations, provider errors, explicit exposures, and tracking events appear under the Feature flags watcher. Private attributes are redacted from instrumentation details. ## API reference - [`createOpenFeatureFlagsProvider`](https://www.beignetjs.com/typedoc/functions/_beignet_provider-flags-openfeature.createOpenFeatureFlagsProvider.html)