Issue #838: Clarify use of PureComponent and memo in changelog (#842)

ynejati · FredyC · vkrol · web-flow · commit d1f731492c3d · 2020-02-26T14:20:45.000+01:00
* Issue #838: Clarify use of PureComponent and memo in changelog * Improve changelog and readme docs * Feedback. Lowercase observer in readme, better changelog link, shouldComponent update to lowercase as well. * Add 'the' before observer * Update README.md Co-Authored-By: Veniamin Krol <153412+vkrol@users.noreply.github.com> Co-authored-by: Daniel K. <FredyC@users.noreply.github.com> Co-authored-by: Veniamin Krol <153412+vkrol@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -74,7 +74,7 @@
 **Improvements**
 
 -   Hook based components are now supported by mobx-react (in fact, the package is now implemented using hooks)
--   Using `PureComponent` is now _recommended_ for class-based components or `React.memo` for functional ones.
+-   Class based `observer` components are now _recommended_ to extend `React.PureComponent`. Functional `observer` components are now automatically wrapped in `React.memo` internally. See section in [README](https://mobx.js.org/README.html#observercomponentclass) for more details.
 -   For `observer` based components, there will now be an additional `Observer` component in the tree.
 -   Two new hooks have been exposed, in case you want to manage local state in observable: `useLocalStore` and `useAsObservableSource`.
 -   `MobXProviderContext` is now exposed from the package, in case you want to consume the context used by `Provider` with a `useContext` hook.
diff --git a/README.md b/README.md
@@ -51,12 +51,19 @@ For greenfield projects you might want to consider to use [mobx-react-lite](http
 
 Please check [mobx.js.org](https://mobx.js.org) for the general documentation. The documentation below highlights some specifics.
 
-### `observer(componentClass)`
+### `observer(component)`
 
-Function (and decorator) that converts a React component definition, React component class or stand-alone render function into a reactive component, which tracks which observables are used by `render` and automatically re-renders the component when one of these values changes.
+Function (and decorator) that converts a React component definition, React component class, or stand-alone render function, into a reactive component. A converted component will track which observables are used by its effective `render` and automatically re-render the component when one of these values changes.
+
+#### Functional Components
+
+`React.memo` is automatically applied to functional components provided to `observer`. `observer` does not accept a functional component already wrapped in `React.memo`, or an `observer`, in order to avoid consequences that might arise as a result of wrapping it twice.
+
+#### Class Components
 
 When using component classes, `this.props` and `this.state` will be made observables, so the component will react to all changes in props and state that are used by `render`.
-Note that `observer` automatically applies `React.memo` to any functional component you pass to it, however class components should extend `PureComponent` instead of `Component`
+
+`shouldComponentUpdate` is not supported. As such, it is recommended that class components extend `React.PureComponent`. The `observer` will automatically patch non-pure class components with an internal implementation of `React.PureComponent` if necessary.
 
 See the [MobX](https://mobxjs.github.io/mobx/refguide/observer-component.html) documentation for more details.
 
diff --git a/src/observer.tsx b/src/observer.tsx
@@ -27,7 +27,7 @@ export function observer<T extends IReactComponent>(component: T): T {
 
     if (ReactMemoSymbol && component["$$typeof"] === ReactMemoSymbol) {
         throw new Error(
-            "Mobx observer: You are trying to use 'observer' on function component wrapped to either another observer or 'React.memo'. The observer already applies 'React.memo' for you."
+            "Mobx observer: You are trying to use 'observer' on a function component wrapped in either another observer or 'React.memo'. The observer already applies 'React.memo' for you."
         )
     }
 

Original file line number	Diff line number	Diff line change
`@@ -27,7 +27,7 @@ export function observer<T extends IReactComponent>(component: T): T {`
`27`	`27`
`28`	`28`	`if (ReactMemoSymbol && component["$$typeof"] === ReactMemoSymbol) {`
`29`	`29`	`throw new Error(`
`30`		`- "Mobx observer: You are trying to use 'observer' on function component wrapped to either another observer or 'React.memo'. The observer already applies 'React.memo' for you."`
	`30`	`+ "Mobx observer: You are trying to use 'observer' on a function component wrapped in either another observer or 'React.memo'. The observer already applies 'React.memo' for you."`
`31`	`31`	`)`
`32`	`32`	`}`
`33`	`33`