Feature Flags

react/react/.claude/skills/feature-flags

by reactb618bbb44226No license250K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated yesterday

Use when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging channel-specific test failures, or adding new flags to React.

Instructions onlySoftware Development

AI-generated overview

Guides React contributors on feature flag files, @gate test gating, adding flags, and debugging channel-specific test failures.

What it does: This skill explains how React feature flags are organized across the default file and channel fork files, and how tests are gated with the @gate pragma or inline gate() assertions. It gives a step-by-step procedure for adding a new flag, including setting VARIANT values in fork files. It also covers checking flag states with /flags and diagnosing channel-specific test failures.
When to use it: Use it when feature flag tests fail, when flags need updating, when you need to understand @gate pragmas, when debugging channel-specific test failures, or when adding new flags to React.
Requirements: No scripts are shipped; it is instructions only. It assumes a React repository checkout with the feature flag files and test tooling, and references commands such as /flags and /test.

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:

javascript

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

// @gate enableViewTransitionit('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:

javascript

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');  }});

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):

bash

/test www <pattern>              # __VARIANT__ = true/test www variant false <pattern> # __VARIANT__ = 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')

Source and attribution

Source:react/reactin.claude/skills/feature-flagsat commitb618bbb

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Feature Flags

React Feature Flags

Flag Files

Gating Tests

`@gate` pragma (test-level)

`gate()` inline (assertion-level)

Adding a New Flag

Checking Flag States

`VARIANT` Flags (GKs)

Debugging Channel-Specific Failures

Common Mistakes

Source and attribution

More from react/react

Verify

Test

Flow

Flags

Fix

Extract Errors

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices

Feature Flags

React Feature Flags

Flag Files

Gating Tests

@gate pragma (test-level)

gate() inline (assertion-level)

Adding a New Flag

Checking Flag States

__VARIANT__ Flags (GKs)

Debugging Channel-Specific Failures

Common Mistakes

Source and attribution

More from react/react

Verify

Test

Flow

Flags

Fix

Extract Errors

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices

`@gate` pragma (test-level)

`gate()` inline (assertion-level)

`VARIANT` Flags (GKs)