feature flags
- Repo stars 245,422
- Author repo react
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @facebook · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 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 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:
```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');
}
});
```
## 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
/test www <pattern> # __VARIANT__ = true
/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')`
Sections and files
Listed in source order.
sections -> Flag Files → Gating Tests → @gate pragma (test-level) → gate() inline (assertion-level) → Adding a New Flag → Checking Flag States
terms -> Forgetting both variants · Using @gate for behavior differences · Missing fork files · Wrong gate syntax
files/cmd -> packages/shared/ReactFeatureFlags.js · __EXPERIMENTAL__ · packages/shared/forks/ReactFeatureFlags.www.js · __VARIANT__ · packages/shared/forks/ReactFeatureFlags.native-fb.js · packages/shared/forks/ReactFeatureFlags.test-renderer.js · @gate · gate()
body sha256 -> ab070c03162b
Flag Files
File · Purpose
packages/shared/ReactFeatureFlags.js· Default flags (canary),__EXPERIMENTAL__overridespackages/shared/forks/ReactFeatureFlags.www.js· www channel,__VARIANT__overridespackages/shared/forks/ReactFeatureFlags.native-fb.js· React Native,__VARIANT__overridespackages/shared/forks/ReactFeatureFlags.test-renderer.js· Test renderer@gate pragma (test-level)
Use when the feature is completely unavailable without the flag:
gate() inline (assertion-level)
Use when the feature exists but behavior differs based on flag:
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
/flagsto view states across channels. See theflagsskill for full command options.