Eliminate setState-in-effect anti-patterns across 16 sites

[JohnRDOrazio]

Context

eslint-config-next 16 introduced the react-hooks/set-state-in-effect rule, which flags setState calls made synchronously inside a useEffect body. This pattern produces cascading renders, makes data flow harder to reason about, and is almost always a sign that the state can be derived, lifted, or assigned during the triggering event instead.

The rule is currently set to "warn" in eslint.config.mjs:9-11 so it doesn't gate CI:

// TODO: address these new react-hooks rules from eslint-config-next 16
// See: https://react.dev/learn/you-might-not-need-an-effect
"react-hooks/set-state-in-effect": "warn",
"react-hooks/immutability": "warn",

This issue tracks the cleanup of all current set-state-in-effect warnings so the rule can graduate to "error".

Scope

16 unique sites across 12 files. (Category A ended up with 6 sites, not 7 — one entry moved to Category D; see below.) Grouping by remedy makes the work tractable — most of these are textbook patterns from React's you-might-not-need-an-effect docs.

Category A — Reset-on-prop-change (use key prop or derived state) — ✅ complete

When a parent prop changes and a child resets its local state to match, the React-recommended fix is for the parent to give the child a different key prop so it remounts naturally — no effect required.

Line numbers below were refreshed against dev on 2026-08-19. Several had drifted since this issue was written.

Dependency on #224. The one site already fixed here was fixed by the key={iri} remount, and #224 is scoped to revisit that remount (evaluating keepPreviousData + manual reset vs. Suspense vs. view transitions). If #224 removes the remount, PropertyDetailPanel.tsx:260 returns and Category A grows back to 7. Settle #224's direction before or alongside this category — the two are working the same mechanism from opposite ends.

• components/editor/AddEntityDialog.tsx:96 — reset dialog state when open flips — PR fix: eliminate setState-in-effect anti-patterns (Category A complete, #200) — fixes #364 #365 (state moved into an inner form that Radix unmounts on close)
• components/editor/AddEntityDialog.tsx:120 — setIri(generateIri(label)) derived from label — PR fix: eliminate setState-in-effect anti-patterns (Category A complete, #200) — fixes #364 #365 (now iriOverride ?? generatedIri)
• components/editor/PropertyDetailPanel.tsx:260 — reset edit state when propertyIri changes — already resolved by commit c22733a (PR feat: preserve entity selection across viewer/editor modes #104, merged 2026-05-02), which applied exactly this category's remedy: key={iri} on all three detail panels in both editor layouts, dropping the redundant navigate-away effects. Landed ~1 h after this issue was filed, so it was never reflected here. See the Eliminate detail-panel flash when switching entities in the tree #224 caveat below.
• components/editor/PropertyDetailPanel.tsx:293 — restored-draft init when both restoredDraft and propertyIri are present — PR fix: eliminate setState-in-effect anti-patterns (Category A complete, #200) — fixes #364 #365 (seeded during render; useEntityAutoSave now exposes restoredDraft on the first render). PR fix: make annotation placeholder rows respect property cardinality (closes #203) #273 edits lines inside this effect and will need to rebase onto it.
• components/editor/DeleteImpactAnalysis.tsx:32 — reset state when entityIri/projectId change — PR fix: eliminate setState-in-effect anti-patterns (Category A complete, #200) — fixes #364 #365 (React Query + key={entityIri}; also fixed Delete is permanently disabled for entities with no references #364)
• app/page.tsx:75 — setNextPageError(null) when filter/debouncedSearch change — PR fix: eliminate setState-in-effect anti-patterns (Category A complete, #200) — fixes #364 #365 (error tagged with its list identity and derived during render)

Category B — Browser-API subscriptions (use useSyncExternalStore) — ✅ resolved (1 fixed, 1 removed by #154)

External stores (matchMedia, websockets) belong in useSyncExternalStore, not useEffect + setState.

• components/editor/TurtleEditor.tsx:110 — setSystemTheme from window.matchMedia("(prefers-color-scheme: dark)") — PR fix: read prefers-color-scheme via useSyncExternalStore (Category B, #200) #367 (new usePrefersDarkMode hook built on useSyncExternalStore)
• lib/hooks/useCollaborationStatus.ts:132 — websocket connect/disconnect lifecycle — no work needed here: #154 deletes this implementation. Issue #140 is that the hook pointed at the lint endpoint; refactor: decouple useCollaborationStatus from lint WebSocket endpoint #154 replaces the whole body with a stub that has no useState/useEffect, so the warning goes with it. Wrapping it in a store first would conflict with refactor: decouple useCollaborationStatus from lint WebSocket endpoint #154 for no benefit.

Category C — Server-data-derived (overlaps with #89) — ✅ complete

State mirrored from a query response. Best fix is to derive the value via React Query's select option, or compute it in render rather than mirroring into local state.

• lib/context/BranchContext.tsx:119 — setCurrentBranch after response arrives — PR fix: derive server-backed state instead of mirroring it (Category C, #200) #369 (currentBranch is now a useMemo over the query response and the visitor's explicit selection)
• lib/context/BranchContext.tsx:152 — setInitialBranchHandled(true) after init — PR fix: derive server-backed state instead of mirroring it (Category C, #200) #369 (flag removed entirely; precedence selectedBranch ?? initialBranch ?? storedBranch expresses it directly)
• app/projects/[id]/suggestions/page.tsx:88 — manual setIsLoadingSessions/setSessions/setSessionsError from a fetch — PR fix: derive server-backed state instead of mirroring it (Category C, #200) #369 (new useSuggestionSessions React Query hook; Migrate manual data fetching to React Query hooks #89's migration had already landed via PR feat: migrate data fetching to React Query hooks #105, this was the leftover)

Category D — One-shot init / event-driven UI (move to handler or useState initializer)

Work that runs once on mount or in response to a discrete event should live in a useState lazy initializer or in the handler that triggered it, not in an effect.

• app/auth/error/page.tsx:39 — PR fix: eliminate setState-in-effect anti-patterns (Category D, #200) #362 — setRetryCount((c) => c + 1) inside countdown tick; move into the interval handler that also updates setCountdown
• app/page.tsx:31 — PR fix: eliminate setState-in-effect anti-patterns (Category D, #200) #362 — one-shot auth-default-applied flag with ref guard; use a useState lazy initializer that reads isAuthenticated once
• app/settings/page.tsx:342 — PR fix: eliminate setState-in-effect anti-patterns (Category D, #200) #362 — setHighlightedSetting(hash) for hash-scroll spy; move into the hash-listener handler
• components/editor/shared/EntityTreeToolbar.tsx:52 — PR fix: eliminate setState-in-effect anti-patterns (Category D, #200) #362 — setShowTip(true) from localStorage read on mount; use useState(() => !localStorage.getItem(TIP_DISMISSED_KEY)) lazy initializer
• app/projects/[id]/editor/page.tsx:311 — setOntologyNamespace / setOntologyPrefix / setIriPattern / setNextNumeric from a one-shot prefix-map scan, latched by iriPatternDetectedRef and reset only after a save — moved here from Category A (it is a one-shot init, not a reset-on-prop-change). Needs a decision before implementation: removing the effect means choosing between keeping the latch and deriving live with useMemo, which changes when iriPattern / nextNumeric update and therefore what IRIs get minted.

Recommended order

1. Category A first (7 sites). Largest cluster, single canonical fix (key prop or derivation), and exercises the test suite hardest because the affected components have substantial coverage.
2. Category D (4 sites). Small, mostly mechanical fixes; gets the warning count down quickly.
3. Category B (2 sites). useSyncExternalStore migration is more involved but well-isolated.
4. Category C (3 sites). Best done alongside the Migrate manual data fetching to React Query hooks #89 React Query migration so the changes share PRs and review context — the suggestions-page site in particular is a natural addition to issue Migrate manual data fetching to React Query hooks #89's Phase 2.

Done criteria

• All 16 sites refactored — 10 done (1 via PR feat: preserve entity selection across viewer/editor modes #104, 5 via PR fix: eliminate setState-in-effect anti-patterns (Category A complete, #200) — fixes #364 #365, 1 via PR fix: read prefers-color-scheme via useSyncExternalStore (Category B, #200) #367, 3 via PR fix: derive server-backed state instead of mirroring it (Category C, #200) #369), 4 in review (Category D, PR fix: eliminate setState-in-effect anti-patterns (Category D, #200) #362), 1 disappears with PR refactor: decouple useCollaborationStatus from lint WebSocket endpoint #154, 1 open: the re-filed editor/page.tsx:311, which needs a latch-vs-live-derivation decision. dev emits 15 warnings; fix: eliminate setState-in-effect anti-patterns (Category A complete, #200) — fixes #364 #365 → 10, fix: read prefers-color-scheme via useSyncExternalStore (Category B, #200) #367 → 9, fix: derive server-backed state instead of mirroring it (Category C, #200) #369 → 6, fix: eliminate setState-in-effect anti-patterns (Category D, #200) #362 → 2, refactor: decouple useCollaborationStatus from lint WebSocket endpoint #154 → 1.
• react-hooks/set-state-in-effect upgraded from "warn" to "error" in eslint.config.mjs
• react-hooks/immutability evaluated and either fixed or kept at "warn" with a documented reason
• No new set-state-in-effect warnings introduced (CI now enforces)

Related

• Migrate manual data fetching to React Query hooks #89 — Migrate manual data fetching to React Query hooks (overlaps on Category C only)
• Eliminate detail-panel flash when switching entities in the tree #224 — Eliminate detail-panel flash when switching entities (revisits the key={iri} remount that resolved one Category A site)
• PR feat: preserve entity selection across viewer/editor modes #104 — introduced that remount (commit c22733a)
• PR fix: eliminate setState-in-effect anti-patterns (Category D, #200) #362 — Category D (4 sites)
• PR fix: eliminate setState-in-effect anti-patterns (Category A complete, #200) — fixes #364 #365 — Category A (5 sites, category complete); also fixes Delete is permanently disabled for entities with no references #364
• PR fix: read prefers-color-scheme via useSyncExternalStore (Category B, #200) #367 — Category B (usePrefersDarkMode), stacked on fix: eliminate setState-in-effect anti-patterns (Category A complete, #200) — fixes #364 #365
• PR fix: derive server-backed state instead of mirroring it (Category C, #200) #369 — Category C (3 sites, category complete), stacked on fix: read prefers-color-scheme via useSyncExternalStore (Category B, #200) #367
• PR refactor: decouple useCollaborationStatus from lint WebSocket endpoint #154 / refactor: decouple useCollaborationStatus from lint WebSocket endpoint #140 — removes the other Category B site outright
• Delete is permanently disabled for entities with no references #364 — Delete permanently disabled for entities with no references (surfaced by the Category A refactor)
• React docs: You Might Not Need an Effect