Merge pull request #4496 from reduxjs/docs/tutorials-instructions

Author: markerikson

docs/components/_FundamentalsWarning.mdx

@@ -0,0 +1,10 @@
+:::caution
+
+Note that **this tutorial intentionally shows older-style Redux logic patterns that require more code than the "modern Redux" patterns with Redux Toolkit we teach as the right approach for building apps with Redux today**, in order to explain the principles and concepts behind Redux. It's _not_ meant to be a production-ready project.
+
+See these pages to learn how to use "modern Redux" with Redux Toolkit:
+
+- [**The full "Redux Essentials" tutorial**](../tutorials/essentials/part-1-overview-concepts.md), which teaches "how to use Redux, the right way" with Redux Toolkit for real-world apps. **We recommend that all Redux learners should read the "Essentials" tutorial!**
+- [**Redux Fundamentals, Part 8: Modern Redux with Redux Toolkit**](../tutorials/fundamentals/part-8-modern-redux.md), which shows how to convert the low-level examples from earlier sections into modern Redux Toolkit equivalents
+
+:::

docs/introduction/why-rtk-is-redux-today.md

@@ -18,6 +18,16 @@ Whether you're a brand new Redux user setting up your first project, or an exper
 simplify an existing application, **[Redux Toolkit](https://redux-toolkit.js.org/)** can help you
 make your Redux code better.
 
+:::tip
+
+See these pages to learn how to use "modern Redux" with Redux Toolkit:
+
+- [**The "Redux Essentials" tutorial**](../tutorials/essentials/part-1-overview-concepts.md), which teaches "how to use Redux, the right way" with Redux Toolkit for real-world apps,
+- [**Redux Fundamentals, Part 8: Modern Redux with Redux Toolkit**](../tutorials/fundamentals/part-8-modern-redux.md), which shows how to convert the low-level examples from earlier sections of the tutorial into modern Redux Toolkit equivalents
+- [**Using Redux: Migrating to Modern Redux**](../usage/migrating-to-modern-redux.mdx), which covers how to migrate different kinds of legacy Redux logic into modern Redux equivalents
+
+:::
+
 ## How Redux Toolkit Is Different Than the Redux Core
 
 ### What Is "Redux"?
@@ -230,7 +240,7 @@ If you are using the `redux` core package by itself, your code will continue to
 
 See these docs pages and blog posts for more details
 
-- [Redux Essentials: Redux App Structure](../tutorials/essentials/part-2-app-structure.md)
+- [Redux Essentials: Redux Toolkit App Structure](../tutorials/essentials/part-2-app-structure.md)
 - [Redux Fundamentals: Modern Redux with Redux Toolkit](../tutorials/fundamentals/part-8-modern-redux.md)
 - [Redux Style Guide: Best Practices and Recommendations](../style-guide/style-guide.md)
 - [Presentation: Modern Redux with Redux Toolkit](https://blog.isquaredsoftware.com/2022/06/presentations-modern-redux-rtk/)

docs/redux-toolkit/overview.md

@@ -59,7 +59,7 @@ Redux Toolkit includes:
 - [`createEntityAdapter`](https://redux-toolkit.js.org/api/createEntityAdapter): generates a set of reusable reducers and selectors to manage normalized data in the store
 - The [`createSelector` utility](https://redux-toolkit.js.org/api/createSelector) from the [Reselect](https://github.com/reduxjs/reselect) library, re-exported for ease of use.
 
-Redux Toolkit also has a new [**RTK Query data fetching API**](https://redux-toolkit.js.org/rtk-query/overview). RTK Query is a powerful data fetching and caching tool built specifically for Redux. It is designed to simplify common cases for loading data in a web application, eliminating the need to hand-write data fetching & caching logic yourself.
+Redux Toolkit also has the [**RTK Query data fetching API**](https://redux-toolkit.js.org/rtk-query/overview). RTK Query is a powerful data fetching and caching tool built specifically for Redux. It is designed to simplify common cases for loading data in a web application, eliminating the need to hand-write data fetching & caching logic yourself.
 
 ## Documentation
 

docs/tutorials/essentials/part-1-overview-concepts.md

@@ -459,4 +459,4 @@ Redux does have a number of new terms and concepts to remember. As a reminder, h
 
 ## What's Next?
 
-We've seen each of the individual pieces of a Redux app. Next, continue on to [Part 2: Redux App Structure](./part-2-app-structure.md), where we'll look at a full working example to see how the pieces fit together.
+We've seen each of the individual pieces of a Redux app. Next, continue on to [Part 2: Redux Toolkit App Structure](./part-2-app-structure.md), where we'll look at a full working example to see how the pieces fit together.

docs/tutorials/essentials/part-2-app-structure.md

@@ -1,15 +1,15 @@
 ---
 id: part-2-app-structure
-title: 'Redux Essentials, Part 2: Redux App Structure'
-sidebar_label: 'Redux App Structure'
-description: 'The official Redux Essentials tutorial: learn the structure of a typical React + Redux app'
+title: 'Redux Essentials, Part 2: Redux Toolkit App Structure'
+sidebar_label: 'Redux Toolkit App Structure'
+description: 'The official Redux Essentials tutorial: learn the structure of a typical React + Redux Toolkit app'
 ---
 
 import { DetailedExplanation } from '../../components/DetailedExplanation'
 
 :::tip What You'll Learn
 
-- The structure of a typical React + Redux app
+- The structure of a typical React + Redux Toolkit app
 - How to view state changes in the Redux DevTools Extension
 
 :::

docs/tutorials/essentials/part-3-data-flow.md

@@ -23,7 +23,7 @@ import { DetailedExplanation } from '../../components/DetailedExplanation'
 
 ## Introduction
 
-In [Part 1: Redux Overview and Concepts](./part-1-overview-concepts.md), we looked at how Redux can help us build maintainable apps by giving us a single central place to put global app state. We also talked about core Redux concepts like dispatching action objects, using reducer functions that return new state values, and writing async logic using thunks. In [Part 2: Redux App Structure](./part-2-app-structure.md), we saw how APIs like `configureStore` and `createSlice` from Redux Toolkit and `Provider` and `useSelector` from React-Redux work together to let us write Redux logic and interact with that logic from our React components.
+In [Part 1: Redux Overview and Concepts](./part-1-overview-concepts.md), we looked at how Redux can help us build maintainable apps by giving us a single central place to put global app state. We also talked about core Redux concepts like dispatching action objects, using reducer functions that return new state values, and writing async logic using thunks. In [Part 2: Redux Toolkit App Structure](./part-2-app-structure.md), we saw how APIs like `configureStore` and `createSlice` from Redux Toolkit and `Provider` and `useSelector` from React-Redux work together to let us write Redux logic and interact with that logic from our React components.
 
 Now that you have some idea of what these pieces are, it's time to put that knowledge into practice. We're going to build a small social media feed app, which will include a number of features that demonstrate some real-world use cases. This will help you understand how to use Redux in your own applications.
 

docs/tutorials/essentials/part-5-async-logic.md

@@ -29,6 +29,14 @@ So far, all the data we've worked with has been directly inside of our React cli
 
 In this section, we'll convert our social media app to fetch the posts and users data from an API, and add new posts by saving them to the API.
 
+:::tip
+
+Redux Toolkit includes the [**RTK Query data fetching and caching API**](https://redux-toolkit.js.org/rtk-query/overview). RTK Query is a purpose built data fetching and caching solution for Redux apps, and **can eliminate the need to write _any_ thunks or reducers to manage data fetching**. We specifically teach RTK Query as the default approach for data fetching, and RTK Query is built on the same patterns shown in this page.
+
+We'll cover how to use RTK Query starting in [Part 7: RTK Query Basics](./part-7-rtk-query-basics.md).
+
+:::
+
 ### Example REST API and Client
 
 To keep the example project isolated but realistic, the initial project setup already includes a fake in-memory REST API for our data (configured using [the Mock Service Worker mock API tool](https://mswjs.io/)). The API uses `/fakeApi` as the base URL for the endpoints, and supports the typical `GET/POST/PUT/DELETE` HTTP methods for `/fakeApi/posts`, `/fakeApi/users`, and `fakeApi/notifications`. It's defined in `src/api/server.js`.
@@ -170,14 +178,6 @@ However, writing code using this approach is tedious. Each separate type of requ
 
 <br />
 
-:::tip
-
-Redux Toolkit has a new [**RTK Query data fetching API**](https://redux-toolkit.js.org/rtk-query/overview). RTK Query is a purpose built data fetching and caching solution for Redux apps, and **can eliminate the need to write _any_ thunks or reducers to manage data fetching**. We encourage you to try it out and see if it can help simplify the data fetching code in your own apps!
-
-We'll cover how to use RTK Query starting in [Part 7: RTK Query Basics](./part-7-rtk-query-basics.md).
-
-:::
-
 ## Loading Posts
 
 So far, our `postsSlice` has used some hardcoded sample data as its initial state. We're going to switch that to start with an empty array of posts instead, and then fetch a list of posts from the server.

docs/tutorials/essentials/part-7-rtk-query-basics.md

@@ -285,7 +285,13 @@ export const PostsList = () => {
 }
 ```
 
-Conceptually, `<PostsList>` is still doing all the same work it was before, but we were able to replace the multiple `useSelector` calls and the `useEffect` dispatch with a single call to `useGetPostsQuery()`.
+Conceptually, `<PostsList>` is still doing all the same work it was before, but **we were able to replace the multiple `useSelector` calls and the `useEffect` dispatch with a single call to `useGetPostsQuery()`**.
+
+:::tip
+
+You should normally use the query hooks to access cached data in components - you _shouldn't_ write your own `useSelector` calls to access fetched data or `useEffect` calls to trigger fetching!
+
+:::
 
 Each generated query hook returns a "result" object containing several fields, including:
 
@@ -445,13 +451,19 @@ We can see that we have a top-level `state.api` slice, as expected from the stor
 
 RTK Query creates a "cache key" for each unique endpoint + argument combination, and stores the results for each cache key separately. That means that **you can use the same query hook multiple times, pass it different query parameters, and each result will be cached separately in the Redux store**.
 
+:::tip
+
+If you need the same data in multiple components, just call the same query hook with the same arguments in each component! For example, you can call `useGetPostQuery('123')` in three different components, and RTK Query will make sure the data is only fetched once, and each component will re-render as needed.
+
+:::
+
 It's also important to note that **the query parameter must be a _single_ value!** If you need to pass through multiple parameters, you must pass an object containing multiple fields (exactly the same as with `createAsyncThunk`). RTK Query will do a "shallow stable" comparison of the fields, and re-fetch the data if any of them have changed.
 
 Notice that the names of the actions in the left-hand list are much more generic and less descriptive: `api/executeQuery/fulfilled`, instead of `posts/fetchPosts/fulfilled`. This is a tradeoff of using an additional abstraction layer. The individual actions do contain the specific endpoint name under `action.meta.arg.endpointName`, but it's not as easily viewable in the action history list.
 
 :::tip
 
-The Redux team is working on a new RTK Query view for the Redux DevTools that will specifically show RTK Query data in a more usable format. This includes info on each endpoint and cache result, stats on query timing, and much more. This will be added to the DevTools Extension in the near future. For a preview, see:
+The Redux DevTools have an "RTK Query" tab that specifically shows RTK Query data in a more usable format. This includes info on each endpoint and cache result, stats on query timing, and much more:
 
 - [Redux DevTools #750: Add RTK Query-Inspector monitor](https://github.com/reduxjs/redux-devtools/pull/750)
 - [RTK Query Monitor preview demo](https://rtk-query-monitor-demo.netlify.app/)

docs/tutorials/fundamentals/part-1-overview.md

@@ -7,6 +7,9 @@ description: 'The official Fundamentals tutorial for Redux: learn the fundamenta
 
 import { DetailedExplanation } from '../../components/DetailedExplanation'
 
+<!-- prettier-ignore -->
+import FundamentalsWarning from "../../components/_FundamentalsWarning.mdx";
+
 # Redux Fundamentals, Part 1: Redux Overview
 
 :::tip What You'll Learn
@@ -26,18 +29,11 @@ Starting in [Part 3: State, Actions, and Reducers](./part-3-state-actions-reduce
 
 ### How to Read This Tutorial
 
-**This tutorial will teach you "how Redux works"**, as well as _why_ these patterns exist. Fair warning though - learning the concepts is different from putting them into practice in actual apps.
-
-**The initial code will be less concise than the way we suggest writing real app code**, but writing it out long-hand is the best way to learn. Once you understand how everything fits together, we'll look at using Redux Toolkit to simplify things. **Redux Toolkit is the recommended way to build production apps with Redux**, and is built on all of the concepts that we will look at throughout this tutorial. Once you understand the core concepts covered here, you'll understand how to use Redux Toolkit more efficiently.
-
-:::info
-
-If you're looking to learn more about how Redux is used to write real-world applications, please see:
+**This tutorial will teach you "how Redux works"**, as well as _why_ these patterns exist.
 
-- [**The "Modern Redux" page in this tutorial**](./part-8-modern-redux.md), which shows how to convert the low-level examples from earlier sections into the modern patterns we do recommend for real-world usage
-- [**The "Redux Essentials" tutorial**](../essentials/part-1-overview-concepts.md), which teaches "how to use Redux, the right way" for real-world apps, using our latest recommended patterns and practices.
+<FundamentalsWarning />
 
-:::
+Once you understand how everything fits together, we'll look at using Redux Toolkit to simplify things. **Redux Toolkit is the recommended way to build production apps with Redux**, and is built on all of the concepts that we will look at throughout this tutorial. Once you understand the core concepts covered here, you'll understand how to use Redux Toolkit more efficiently.
 
 We've tried to keep these explanations beginner-friendly, but we do need to make some assumptions about what you know already so that we can focus on explaining Redux itself. **This tutorial assumes that you know**:
 

docs/tutorials/fundamentals/part-2-concepts-data-flow.md

@@ -7,6 +7,9 @@ description: 'The official Redux Fundamentals tutorial: learn key Redux terms an
 
 import { DetailedExplanation } from '../../components/DetailedExplanation'
 
+<!-- prettier-ignore -->
+import FundamentalsWarning from "../../components/_FundamentalsWarning.mdx";
+
 # Redux Fundamentals, Part 2: Concepts and Data Flow
 
 :::tip What You'll Learn
@@ -23,6 +26,8 @@ In [Part 1: Redux Overview](./part-1-overview.md), we talked about what Redux is
 In this section, we'll look at those terms and concepts in more detail, and talk more about how data flows
 through a Redux application.
 
+<FundamentalsWarning />
+
 ## Background Concepts
 
 Before we dive into some actual code, let's talk about some of the terms and concepts you'll need to know to use Redux.

docs/tutorials/fundamentals/part-3-state-actions-reducers.md

@@ -7,6 +7,9 @@ description: 'The official Redux Fundamentals tutorial: learn how reducers updat
 
 import { DetailedExplanation } from '../../components/DetailedExplanation'
 
+<!-- prettier-ignore -->
+import FundamentalsWarning from "../../components/_FundamentalsWarning.mdx";
+
 # Redux Fundamentals, Part 3: State, Actions, and Reducers
 
 :::tip What You'll Learn
@@ -29,11 +32,7 @@ In [Part 2: Redux Concepts and Data Flow](./part-2-concepts-data-flow.md), we lo
 
 Now that you have some idea of what these pieces are, it's time to put that knowledge into practice. We're going to build a small example app to see how these pieces actually work together.
 
-:::caution
-
-**The example app is not meant as a complete production-ready project**. The goal is to help you learn core Redux APIs and usage patterns, and point you in the right direction using some limited examples. Also, some of the early pieces we build will be updated later on to show better ways to do things. **Please read through the whole tutorial to see all the concepts in use**.
-
-:::
+<FundamentalsWarning />
 
 ### Project Setup
 

docs/tutorials/fundamentals/part-4-store.md

@@ -7,6 +7,9 @@ description: 'The official Redux Fundamentals tutorial: learn how to create and
 
 import { DetailedExplanation } from '../../components/DetailedExplanation'
 
+<!-- prettier-ignore -->
+import FundamentalsWarning from "../../components/_FundamentalsWarning.mdx";
+
 # Redux Fundamentals, Part 4: Store
 
 :::tip What You'll Learn
@@ -27,6 +30,8 @@ to create a "root reducer" based on the different "slice reducers" for each feat
 
 Now, it's time to pull those pieces together, with the central piece of a Redux app: the **store**.
 
+<FundamentalsWarning />
+
 ## Redux Store
 
 The Redux **store** brings together the state, actions, and reducers that make up your app. The store has several responsibilities:

docs/tutorials/fundamentals/part-5-ui-and-react.md

@@ -22,6 +22,16 @@ In [Part 4: Store](./part-4-store.md), we saw how to create a Redux store, dispa
 
 In this section, we'll add a User Interface for our todo app. We'll see how Redux works with a UI layer overall, and we'll specifically cover how Redux works together with React.
 
+:::caution
+
+Note that **this page and all of the "Essentials" tutorial teach how to use [our modern React-Redux hooks API](https://react-redux.js.org/api/hooks)**. The old-style [`connect` API](https://react-redux.js.org/api/connect) still works, but today we want all Redux users using the hooks API.
+
+Also, the other pages in this tutorial intentionally show older-style Redux logic patterns that require more code than the "modern Redux" patterns with Redux Toolkit we teach as the right approach for building apps with Redux today, in order to explain the principles and concepts behind Redux.
+
+See [**the "Redux Essentials" tutorial**](../essentials/part-1-overview-concepts.md) for full examples of "how to use Redux, the right way" with Redux Toolkit and React-Redux hooks for real-world apps.
+
+:::
+
 ## Integrating Redux with a UI
 
 Redux is a standalone JS library. As we've already seen, you can create and use a Redux store even if you don't have a user interface set up. This also means that **you can use Redux with any UI framework** (or even without _any_ UI framework), and use it on both client and server. You can write Redux apps with React, Vue, Angular, Ember, jQuery, or vanilla JavaScript.

docs/tutorials/fundamentals/part-6-async-logic.md

@@ -5,6 +5,9 @@ sidebar_label: 'Async Logic and Data Fetching'
 description: 'The official Redux Fundamentals tutorial: learn how to use async logic with Redux'
 ---
 
+<!-- prettier-ignore -->
+import FundamentalsWarning from "../../components/_FundamentalsWarning.mdx";
+
 # Redux Fundamentals, Part 6: Async Logic and Data Fetching
 
 :::tip What You'll Learn
@@ -30,6 +33,16 @@ So far, all the data we've worked with has been directly inside of our React+Red
 
 In this section, we'll update our todo app to fetch the todos from an API, and add new todos by saving them to the API.
 
+<FundamentalsWarning />
+
+:::tip
+
+Redux Toolkit includes the [**RTK Query data fetching and caching API**](https://redux-toolkit.js.org/rtk-query/overview). RTK Query is a purpose built data fetching and caching solution for Redux apps, and **can eliminate the need to write _any_ thunks or reducers to manage data fetching**. We specifically teach RTK Query as the default approach for data fetching, and RTK Query is built on the same patterns shown in this page.
+
+Learn how to use RTK Query for data fetching in [Redux Essentials, Part 7: RTK Query Basics](../essentials/part-7-rtk-query-basics.md).
+
+:::
+
 ### Example REST API and Client
 
 To keep the example project isolated but realistic, the initial project setup already included a fake in-memory REST API for our data (configured using [the Mirage.js mock API tool](https://miragejs.com/)). The API uses `/fakeApi` as the base URL for the endpoints, and supports the typical `GET/POST/PUT/DELETE` HTTP methods for `/fakeApi/todos`. It's defined in `src/api/server.js`.