React Feature Flags

Flag Files

Gating Tests

@gate pragma (test-level)

Use when the feature is completely unavailable without the flag:

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

gate() inline (assertion-level)

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

javascript
1it('renders component', async () => {
2  await act(() => root.render(<App />));
3
4  if (gate(flags => flags.enableNewBehavior)) {
5    expect(container.textContent).toBe('new output');
6  } else {
7    expect(container.textContent).toBe('legacy output');
8  }
9});

Adding a New Flag

1. Add to ReactFeatureFlags.js with default value
2. Add to each fork file (*.www.js, *.native-fb.js, etc.)
3. If it should vary in www/RN, set to __VARIANT__ in the fork file
4. 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
1/test www <pattern>              # __VARIANT__ = true
2/test www variant false <pattern> # __VARIANT__ = false

Debugging Channel-Specific Failures

1. Run /flags --diff <channel1> <channel2> to compare values
2. Check @gate conditions - test may be gated to specific channels
3. Run /test <channel> <pattern> to isolate the failure
4. 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')