diff --git a/doc/null_safety/null_safe_migration.md b/doc/null_safety/null_safe_migration.md index b87294d0d..7a8b4d6d7 100644 --- a/doc/null_safety/null_safe_migration.md +++ b/doc/null_safety/null_safe_migration.md @@ -206,12 +206,18 @@ of the null safety and required props docs for instructions on how to handle the #### connect -For connect, either +For connect, either: - Disable validation using the instructions linked above - Note: for now, this must be done manually, but we'll be adding a codemod to help do this automatically for `connect`: https://github.com/Workiva/over_react_codemod/issues/295 - Refactor your component to instead utilize [OverReact Redux hooks](../over_react_redux_documentation.md#hooks), which avoid this problem by accessing store data and dispatchers directly in the component as opposed to passing it in via props. +We generally recommend using hooks over `connect`, since the API is simpler, and in over_react is more convenient and doesn't involve worrying about required prop validation. + +However, for existing components, converting them to function components may be non-trivial depending on other logic within components that needs to be migrated. + +So, for this migration, you'll want to decide whether converting to function components is worth the effort. + #### Implementing abstract `Ref`s After migrating to null-safety, it may be necessary to add left side typing on `Ref`s when overriding abstract getters as shown in the example below: diff --git a/doc/over_react_redux_documentation.md b/doc/over_react_redux_documentation.md index 52d6e9eb6..08ab27b77 100644 --- a/doc/over_react_redux_documentation.md +++ b/doc/over_react_redux_documentation.md @@ -10,6 +10,10 @@ A Dart wrapper for React Redux, providing targeted state updates. - [Running the Examples](#running-the-examples) - **[Using it in your project](#using-it-in-your-project)** - **[ReduxProvider](#reduxprovider)** +- **[Hooks](#hooks)** + - [useSelector](#useselector) + - [useDispatch](#usedispatch) + - [useStore](#usestore) - **[Connect](#connect)** - [`connect` Parameters](#connect-parameters) - [mapStateToProps](#mapstatetoprops) @@ -22,10 +26,6 @@ A Dart wrapper for React Redux, providing targeted state updates. - [context](#context) - [pure](#pure) - [forwardRef](#forwardref) -- **[Hooks](#hooks)** - - [useSelector](#useselector) - - [useDispatch](#usedispatch) - - [useStore](#usestore) - **[Using Multiple Stores](#using-multiple-stores)** - **[Using Redux DevTools](#using-redux-devtools)** - [Integrating with DevTools](#integration-with-devtools) @@ -168,6 +168,9 @@ A wrapper around the JS react-redux `connect` function that supports OverReact c > See: +> ![TIP] +> connect still works and is supported. However, we recommend using the hooks API as the default. + **Example:** ```dart @@ -299,10 +302,18 @@ class CounterProps = UiProps with CounterPropsMixin, OtherPropsMixin; > [More information about the `connect` function](https://react-redux.js.org/api/connect#connect) ## Hooks + OverReact exposes wrappers around React Redux hook APIs, which serve as an alternative to the existing [`connect()`](#connect) Higher Order Component. These APIs allow you to subscribe to the Redux store and dispatch actions, without having to wrap your components in [`connect()`](#connect). +> [!TIP] +> **We recommend using the React-Redux hooks API as the default approach in your React components.** +> +> The existing connect API still works and will continue to be supported, but the hooks API is simpler, +> requires less OverReact boilerplate, and doesn't involve suppressing validation for required props +> (see [connect](#connect) docs for more info). + > See: As with [`connect()`](#connect), you should start by wrapping your entire application in a @@ -731,4 +742,4 @@ When an enum `Action` is used the value of the action in the enum will be used {"type": "ACTION_1"} ``` -For a more encoding details check out the [redux_remote_devtools](https://pub.dev/packages/redux_remote_devtools) \ No newline at end of file +For a more encoding details check out the [redux_remote_devtools](https://pub.dev/packages/redux_remote_devtools)