RFC: Stop reporting stable dependencies as "unnecessary" in useExhaustiveDependencies

[mdevils]

Summary

Biome's useExhaustiveDependencies currently reports a diagnostic when a "stable" value (e.g. a useState setter or a useRef result) is included in a hook's dependency array. The official ESLint react-hooks/exhaustive-deps rule does not report this — it silently accepts stable values in the dependency array. This RFC proposes aligning Biome's behavior with the ESLint rule by no longer treating the presence of stable dependencies as a diagnostic-worthy issue.

Motivation

Current behavior comparison

Scenario	ESLint exhaustive-deps	Biome useExhaustiveDependencies
Missing dependency in array	⚠️ Reports	⚠️ Reports
Dependency in array but not used in callback at all	⚠️ Reports	⚠️ Reports
Stable dependency (e.g. setState) included in array	✅ No diagnostic	⚠️ Reports as unnecessary

The inconsistency

When a developer writes:

const [name, setName] = useState("");

useEffect(() => {
  setName("hello");
}, [setName]); // <-- Biome reports: "This hook specifies more dependencies than necessary: setName"

Biome flags setName as an unnecessary dependency and suggests removing it. The ESLint react-hooks/exhaustive-deps rule, however, does not report this. It recognizes setName as stable and simply doesn't require it — but it also doesn't complain if the developer chooses to include it.

Why the ESLint behavior is more correct

1. Including stable dependencies is not wrong. React's documentation states that stable values like useState setters, useReducer dispatch, and useRef refs maintain the same identity across renders. Including them in the dependency array is harmless — it doesn't cause unnecessary re-renders or stale closures. It's simply redundant.

2. It's a matter of developer intent and code style. Some developers and teams prefer to explicitly list all values used inside the callback, including stable ones, for readability and to make dependencies self-documenting. Others prefer a minimal array. Neither approach is incorrect.

3. The current diagnostic is misleading. Biome's message says "Specifying more dependencies than required can lead to unnecessary re-rendering and degraded performance" — but this is not true for stable dependencies. Since their identity never changes, including them has zero performance impact. The diagnostic implies a problem that doesn't exist.

4. It creates friction when migrating from ESLint. Users migrating from ESLint to Biome encounter new diagnostics on code that was previously considered valid. This is a common pain point reported by the community (see #630).

5. The official ESLint rule is the de facto standard. The eslint-plugin-react-hooks package is maintained by the React team itself. Aligning with its behavior reduces surprise and increases trust in Biome as a drop-in replacement.

What "stable" means

Both Biome and the ESLint rule understand the concept of stable return values. The ESLint rule knows that certain hooks produce values that never change:

• useState setter (second element)
• useReducer dispatch (second element)
• useRef return value
• useTransition startTransition (second element)

Biome has the same built-in knowledge and also allows configuring custom hooks via the stableResult option. The difference is only in what happens when a stable value appears in the dependency array.

Proposal

Stop emitting a diagnostic when a known-stable dependency is included in the dependency array.

Specifically:

• Biome should not report setName as unnecessary in [name, setName] when setName comes from useState.
• Biome should not report ref as unnecessary in [ref] when ref comes from useRef.
• The same applies to any value configured as stable via the stableResult hook option.

Biome should continue to report:

• Missing dependencies (values used in callback but not listed).
• Truly unnecessary dependencies (values listed but not referenced in the callback at all).

the team prefers a more conservative approach, an alternative would be to change the default of reportUnnecessaryDependencies to false — but this would also suppress diagnostics for genuinely unused dependencies, which is less desirable.

Alternatives considered

1. Add a separate option for stable dependency reporting

A new option like reportStableDependencies: false (defaulting to false) could be introduced. This is viable but adds configuration surface for what is arguably just a bug fix in alignment with the upstream rule.

2. Keep current behavior

The current behavior is intentional and could be seen as a stricter, more opinionated stance: if a dependency is known to never change, listing it is noise. Teams that prefer minimal dependency arrays may actually appreciate this diagnostic. Biome doesn't have to match ESLint 1:1 on every decision — it's a separate tool with its own philosophy.

3. Split into two rules (that can be too complicated to maintain)

Issue #630 proposed splitting useExhaustiveDependencies into two separate rules: one for missing dependencies and one for unnecessary dependencies. While this would give users more granular control, it adds a lot of complexity.

Migration / breaking change considerations

This is a diagnostic reduction — code that currently triggers a warning would no longer trigger one. No previously-valid code would start being flagged. This means:

• CI pipelines using --error-on-warnings would see fewer failures, not more.
• Existing biome-ignore comments for stable dependency warnings would become unnecessary (but harmless).
• The reportUnnecessaryDependencies option would remain useful for controlling diagnostics about genuinely unused dependencies.

This could be considered a minor behavioral change suitable for a patch or minor release, not a breaking change.

References

• Biome useExhaustiveDependencies documentation
• ESLint react-hooks/exhaustive-deps documentation
• ESLint plugin source — stable hook detection
• Issue #630 — Break useExhaustiveDependencies into two rules
• Issue #1128 — Configurable Stable Hooks
• Discussion #1034 — Configurable Stable Hooks in biome.json
• Discussion #2509 — biome-ignore for specific dependency
• facebook/react#20205 — Allow custom list of hooks to ignore on exhaustive-deps
• PR #8401 — Refactor of useExhaustiveDependencies (introduced reportUnnecessaryDependencies)

[silvenon]

I prefer Biome's take on this because redundant dependencies obscure dependecies that actually matter, so they hinder understanding dynamics of hook, which is sometimes really tricky to get right. I would prefer to eliminate all useless dependencies.

I disliked about the official rule that it doesn't care whether a redundant dependency is included or not instead of teaching people that setState and dispatch don't change. Some juniors don't know this, and it's a useful thing to know.

But I understand wanting to align Biome with the official rule.

[arendjr]

I voted for creating an option for this, and I would suggest the default behaviour to stay as it is. This way, it's not a breaking change for Biome users, we also improve the situation for new users that prefer strictness/tidyness (as we do today), yet we also give users that really want to cling to ESLint's way of doing things the option to disable the behaviour.

[hilja]

Correct me if I'm wrong here but useEffectEvent is also a "stable dependency".