From 803edfc5814990417bd2c49dfd26a2d8c08e19e6 Mon Sep 17 00:00:00 2001
From: tomeelog <tomeelog@gmail.com>
Date: Thu, 2 Apr 2026 18:35:48 +0200
Subject: [PATCH] docs(react-integration): add tip on eslint-plugin-react-hooks
 compat with observer

When a component is wrapped with `observer` using an arrow function
(the most common pattern in examples), `eslint-plugin-react-hooks` rules
such as `rules-of-hooks` and `exhaustive-deps` silently stop working
because the plugin does not recognise the wrapped result as a React
component.

Add a new collapsible tip section that:
- explains why the problem occurs
- shows that using a named function inside `observer` fixes it
- cross-references the displayName tip since both share the same solution
- mentions the `componentWrapperFunctions` eslint-plugin-react option
  as a partial workaround (and clarifies its limitations)

Related: https://github.com/mobxjs/mobx/issues/4594
---
 docs/react-integration.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/react-integration.md b/docs/react-integration.md
index 2d25d9296..b86c41a08 100644
--- a/docs/react-integration.md
+++ b/docs/react-integration.md
@@ -405,6 +405,35 @@ Now you can see component names:
 
 </details>
 
+<details id="eslint-hooks"><summary>**Tip:** `eslint-plugin-react-hooks` compatibility with `observer`<a href="#eslint-hooks" class="tip-anchor"></a>
+</summary>
+
+By default, [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks) rules (such as `rules-of-hooks` and `exhaustive-deps`) only recognize components defined as named functions or arrow functions directly assigned to a variable. When you write:
+
+```javascript
+// Arrow function — ESLint react-hooks rules will NOT check this component
+const MyComponent = observer(props => { ... })
+```
+
+ESLint cannot tell that `observer`'s return value is a component, so the hooks rules are silently skipped.
+
+The fix is the same as the one for React DevTools display names: **use a named function inside `observer`**:
+
+```javascript
+// Named function — ESLint react-hooks rules WILL check this component ✓
+const MyComponent = observer(function MyComponent(props) {
+    // hooks are now validated by eslint-plugin-react-hooks
+    const [value, setValue] = React.useState(0)
+    return <div>{value}</div>
+})
+```
+
+This pattern also provides accurate names in React DevTools and stack traces. It is the recommended way to define observable components.
+
+If you prefer arrow functions, you can configure [`eslint-plugin-react`](https://github.com/jsx-eslint/eslint-plugin-react#configuration-legacy-eslintrc-) with the `componentWrapperFunctions` setting to teach ESLint about `observer`, but note that this only affects `eslint-plugin-react` rules, not `eslint-plugin-react-hooks`.
+
+</details>
+
 <details id="wrap-order"><summary>{🚀} **Tip:** when combining `observer` with other higher-order-components, apply `observer` first<a href="#wrap-order" class="tip-anchor"></a></summary>
 
 When `observer` needs to be combined with other decorators or higher-order-components, make sure that `observer` is the innermost (first applied) decorator;