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.jswith 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 flagNameor inlinegate()
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__ = falseDebugging Channel-Specific Failures
- Run
/flags --diff <channel1> <channel2>to compare values - Check
@gateconditions - 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
wwwANDwww variant falsefor__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), notgate('name')
