Setting Feature Flags In Storybook

Setting feature flags in Storybook

> [!WARNING]

> Never call featureFlagLogic.actions.setFeatureFlags(...) from a story. It silently

> no-ops in the visual-regression runtime (rendering the flag-OFF branch) while passing

> in jest — so unit tests stay green and the snapshot is wrong. Use the featureFlags

> story parameter instead.

Mental model: boolean flags always work (they ride the always-merged baseline);

variant values need a gate that _only the featureFlags parameter opens correctly_.

How to use it

This is the stable contract — prefer it over anything in "Under the hood" below.

Boolean flags (flag is simply on)

const meta: Meta = {
  title: 'Scenes/MyScene',
  parameters: {
    featureFlags: [FEATURE_FLAGS.MY_FLAG, FEATURE_FLAGS.OTHER_FLAG],
  },
}

Array entries are flags that evaluate to true. This is the common case.

Multivariate flags (pin a specific variant)

For a flag whose value is a variant string (experiment arms, multivariate rollouts), use

the record form — the array form can only express true:

// meta-level: applies to every story in the file
parameters: { featureFlags: { [FEATURE_FLAGS.THEME_OVERRIDE]: 'intent_plus' } }

// per-story: a different arm per story
export const ControlArm: Story = {
    parameters: { featureFlags: { [FEATURE_FLAGS.THEME_OVERRIDE]: 'control' } },
}
export const TreatmentArm: Story = {
    parameters: { featureFlags: { [FEATURE_FLAGS.THEME_OVERRIDE]: 'intent_plus' } },
}

You can mix booleans and variants in one record: { 'some-bool-flag': true, 'my-experiment': 'test_b' }.

> [!IMPORTANT]

> A story's parameters replace the meta's (shallow merge), so a per-story

> featureFlags drops every flag set at the meta level. **Re-list any meta flags you

> still need** — silently losing one renders the flag-off branch and is easy to miss.

Why the obvious approach fails

Setting flags imperatively (featureFlagLogic.actions.setFeatureFlags) works in jest

(NODE_ENV==='test') but not in the built visual-regression Storybook. posthog-js loads

flags and fires onFeatureFlags with an empty set, which dispatches setFeatureFlags

and wipes whatever you set imperatively — so the unit test passes while the snapshot

renders the flag-OFF branch. The featureFlags parameter avoids this by writing flags to

the always-merged baseline instead (below), so the empty callback can't clobber them.

> Do not try to fix this by disabling posthog-js flags (e.g. advanced_disable_feature_flags).

> The app shell (appLogic.showApp) only renders once receivedFeatureFlags is true,

> which is set by that same onFeatureFlags callback — suppress it and every

> Scenes-App/* story stalls behind a 3s timeout and flakes.

Under the hood (implementation detail — may drift)

> This explains _why_ the parameter works, for trust and for anyone extending the harness.

> Treat "How to use it" above as the contract, not this.

withFeatureFlags → setFeatureFlags (frontend/src/mocks/browser.tsx) writes the

flags (array or record) straight to window.POSTHOG_APP_CONTEXT.persisted_feature_flags.

getPersistedFeatureFlags (frontend/src/lib/logic/featureFlagLogic.ts) reads that as

featureFlagLogic's initial value and spyOnFeatureFlags always merges it as the

baseline — so both booleans and pinned variants survive the empty onFeatureFlags

callback. The only production-side support this needs is getPersistedFeatureFlags

accepting the record form (variant values) in addition to the server's array form.

You should not need to touch any of this. If you're extending the harness, that's the seam.

See also

The featureFlags parameter only controls the flag. If a component's render also depends

on other runtime state (localStorage, an APP_CONTEXT field, a kea logic that resolves an

entry), stage that state too — typically in a small wrapper the story renders that sets it

and mounts the logic before rendering the component. Keep that wrapper in the story file;

don't add test-only props to the production component to make it renderable.