feat: add prefer-use-sync-external-store rule

[aidenybai]

New rule (severity: warn) flagging the §11 anti-pattern from React's You Might Not Need an Effect guide.

What it catches

const [snapshot, setSnapshot] = useState(getSnapshot());
useEffect(() => {
  const unsubscribe = store.subscribe(() => setSnapshot(getSnapshot()));
  return unsubscribe;
}, []);

The hand-rolled subscribe pattern reimplements useSyncExternalStore in user space — incorrectly. The hook handles tearing during concurrent renders and SSR snapshots; the manual pattern doesn't. The rule suggests:

const snapshot = useSyncExternalStore(store.subscribe, getSnapshot);

Detector — four-vertex AST match

Real-world false positives are essentially impossible because all four conditions must coincide:

1. useEffect with empty deps []
2. body declares const u = X.subscribe(handler) OR directly invokes a subscription method X.addEventListener(...)
3. cleanup is a return that returns the unsubscribe binding directly OR returns a closure that unsubscribes
4. handler is a single setY(<getter>) whose <getter> is structurally equal to the matching useState's initializer

Subscription method names recognized: subscribe, addEventListener, addListener, on, watch, listen, sub — covers zustand, Redux vanilla, Valtio, Effector, Jotai store API, RxJS observables, and the browser addEventListener shape (matchMedia, navigator.onLine).

The detector also resolves Identifier-passed handlers (the dominant real-world shape):

const onChange = () => setIsOnline(navigator.onLine);   // ← walked back to the inline arrow
window.addEventListener("online", onChange);
return () => window.removeEventListener("online", onChange);

Library safety

Modern store hooks (useAtomValue from Jotai, useStore from zustand v4+, useSelector from react-redux v8+) already use useSyncExternalStore under the hood and are not flagged — the rule only catches code that bypasses the library's hook to roll its own subscription.

Tests — 7 regression cases

• ✅ flags canonical store.subscribe shape (article §11)
• ✅ flags browser-API addEventListener shape (navigator.onLine)
• ✅ flags lazy-initializer variant useState(() => getSnapshot())
• ❌ does NOT flag legitimate chat-connection effect with non-empty deps
• ❌ does NOT flag subscription without paired useState (audit-only)
• ❌ does NOT flag when the setter argument doesn't match the useState initializer
• ❌ does NOT flag when there's no cleanup

Plus a smoke test in run-oxlint.test.ts against a fixture component.

Refactor included

• New SUBSCRIPTION_METHOD_NAMES and UNSUBSCRIPTION_METHOD_NAMES sets in constants.ts (replaces the local 4-element set in advancedEventHandlerRefs — same shape, broader allowlist).
• New areExpressionsStructurallyEqual helper in helpers.ts for the four-vertex match.

Checks

488/488 tests passing locally. Lint, typecheck, format clean. Changeset included (minor bump).

  

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-doctor-website	Ready	Preview, Comment	May 7, 2026 11:48am