feature-flags

Name: feature-flags
Author: facebook

Debug feature flag tests, update flags, and add new React gates.

Source

GitHub

Updated

2026-06-07

// securityLow risk

Prompt only, no code
Open source

Running security audit…

Credentials
Network egress
Code execution
Data access
Supply chain

// install

Copy the install command and let the AI configure it · recommended for beginners

Please install the "feature-flags" skill from askskill:
1. Download https://raw.githubusercontent.com/facebook/react/main/.claude/skills/feature-flags/SKILL.md
2. Save it as ~/.claude/skills/feature-flags/SKILL.md
3. Reload skills and tell me it's ready

// download

Download SKILL.mdInstall manifest ↗

// examples

Debug failing flag tests

Prompt

Help me analyze why this feature flag test is failing. I will provide the error message, related test code, and current flag configuration. Please identify likely causes and suggest fixes with example changes.

Expected

A diagnosis of the failure, the relevant flag or test logic, and actionable fixes.

Understand @gate pragmas

Prompt

Explain how the @gate pragma works in this test, what runtime conditions it controls, and what I should watch for when changing feature flags.

Expected

An explanation of @gate syntax and behavior, including its impact on test coverage and execution paths.

Add a new React feature flag

Prompt

I want to add a new feature flag to a React project. Tell me which files to update, how to name the flag, how to add tests, and how to avoid breaking existing channels or environments.

Expected

A step-by-step checklist for adding the flag, code change suggestions, test coverage guidance, and compatibility considerations.

// docs

React Feature Flags

Flag Files

File	Purpose
`packages/shared/ReactFeatureFlags.js`	Default flags (canary), `__EXPERIMENTAL__` overrides
`packages/shared/forks/ReactFeatureFlags.www.js`	www channel, `__VARIANT__` overrides
`packages/shared/forks/ReactFeatureFlags.native-fb.js`	React Native, `__VARIANT__` overrides
`packages/shared/forks/ReactFeatureFlags.test-renderer.js`	Test renderer

Gating Tests

`@gate` pragma (test-level)

Use when the feature is completely unavailable without the flag:

// @gate enableViewTransition
it('supports view transitions', () => {
  // This test only runs when enableViewTransition is true
  // and is SKIPPED (not failed) when false
});

`gate()` inline (assertion-level)

Use when the feature exists but behavior differs based on flag:

it('renders component', async () => {
  await act(() => root.render(<App />));

  if (gate(flags => flags.enableNewBehavior)) {
    expect(container.textContent).toBe('new output');
  } else {
    expect(container.textContent).toBe('legacy output');
  }
});

Adding a New Flag

Add to ReactFeatureFlags.js with default value
Add to each fork file (*.www.js, *.native-fb.js, etc.)
If it should vary in www/RN, set to __VARIANT__ in the fork file
Gate tests with @gate flagName or inline gate()

Checking Flag States

Use /flags to view states across channels. See the flags skill for full command options.

`VARIANT` Flags (GKs)

Flags set to __VARIANT__ simulate gatekeepers - tested twice (true and false):

/test www <pattern>              # __VARIANT__ = true
/test www variant false <pattern> # __VARIANT__ = false

Debugging Channel-Specific Failures

Run /flags --diff <channel1> <channel2> to compare values
Check @gate conditions - test may be gated to specific channels
Run /test <channel> <pattern> to isolate the failure
Verify flag exists in all fork files if newly added

Common Mistakes

Forgetting both variants - Always test www AND www variant false for __VARIANT__ flags
Using @gate for behavior differences - Use inline gate() if both paths should run
Missing fork files - New flags must be added to ALL fork files, not just the main one
Wrong gate syntax - It's gate(flags => flags.name), not gate('name')