Merge pull request #3738 from reduxjs/docs/2238-docs-updates

markerikson · web-flow · commit d8db6f7bf817 · 2023-09-23T20:06:33.000-04:00
diff --git a/docs/api/configureStore.mdx b/docs/api/configureStore.mdx
@@ -9,8 +9,28 @@ hide_title: true
 
 # `configureStore`
 
-A friendly abstraction over the standard Redux `createStore` function that adds good defaults
-to the store setup for a better development experience.
+The standard method for creating a Redux store. It uses the low-level Redux core `createStore` method internally, but wraps that to provide good defaults to the store setup for a better development experience.
+
+## Purpose and Behavior
+
+A standard Redux store setup typically requires multiple pieces of configuration:
+
+- Combining the slice reducers into the root reducer
+- Creating the middleware enhancer, usually with the thunk middleware or other side effects middleware, as well as middleware that might be used for development checks
+- Adding the Redux DevTools enhancer, and composing the enhancers together
+- Calling `createStore`
+
+Legacy Redux usage patterns typically required several dozen lines of copy-pasted boilerplate to achieve this.
+
+Redux Toolkit's `configureStore` simplifies that setup process, by doing all that work for you. One call to `configureStore` will:
+
+- Call `combineReducers` to combine your slices reducers into the root reducer function
+- Add the thunk middleware and called `applyMiddleware`
+- In development, automatically add more middleware to check for common mistakes like accidentally mutating the state
+- Automatically set up the Redux DevTools Extension connection
+- Call `createStore` to create a Redux store using that root reducer and those configuration options
+
+`configureStore` also offers an improved API and usage patterns compared to the original `createStore` by accepting named fields for `reducer`, `preloadedState`, `middleware`, `enhancers`, and `devtools`, as well as much better TS type inference.
 
 ## Parameters
 
diff --git a/docs/api/createSlice.mdx b/docs/api/createSlice.mdx
@@ -15,7 +15,7 @@ and automatically generates action creators and action types that correspond to
 This API is the standard approach for writing Redux logic.
 
 Internally, it uses [`createAction`](./createAction.mdx) and [`createReducer`](./createReducer.mdx), so
-you may also use [Immer](https://immerjs.github.io/immer/) to write "mutating" immutable updates:
+you may also use [Immer](../usage/immer-reducers.md) to write "mutating" immutable updates:
 
 ```ts
 import { createSlice } from '@reduxjs/toolkit'
@@ -136,16 +136,17 @@ const todosSlice = createSlice({
 
 ### `extraReducers`
 
-One of the key concepts of Redux is that each slice reducer "owns" its slice of state, and that many slice reducers
-can independently respond to the same action type. `extraReducers` allows `createSlice` to respond to other action types
-besides the types it has generated.
+Conceptually, each slice reducer "owns" its slice of state. There's also a natural correspondance between the update logic defined inside `reducers`, and the action types that are generated based on those.
 
-As case reducers specified with `extraReducers` are meant to reference "external" actions, they will not have actions generated in `slice.actions`.
+However, there are many times that a Redux slice may also need to update its own state in response to action types that were defined elsewhere in the application (such as clearing many different kinds of data when a "user logged out" action is dispatched). This can include action types defined by another `createSlice` call, actions generated by a `createAsyncThunk`, RTK Query endpoint matchers, or any other action. In addition, one of the key concepts of Redux is that many slice reducers can independently respond to the same action type.
 
-As with `reducers`, these case reducers will also be passed to `createReducer` and may "mutate" their state safely.
+**`extraReducers` allows `createSlice` to respond and update its own state in response to other action types besides the types it has generated.**
 
-If two fields from `reducers` and `extraReducers` happen to end up with the same action type string,
-the function from `reducers` will be used to handle that action type.
+As with the `reducers` field, each case reducer in `extraReducers` is [wrapped in Immer and may use "mutating" syntax to safely update the state inside](../usage/immer-reducers.md).
+
+However, unlike the `reducers` field, each individual case reducer inside of `extraReducers` will _not_ generate a new action type or action creator.
+
+If two fields from `reducers` and `extraReducers` happen to end up with the same action type string, the function from `reducers` will be used to handle that action type.
 
 ### The `extraReducers` "builder callback" notation
 
@@ -162,6 +163,14 @@ See [the "Builder Callback Notation" section of the `createReducer` reference](.
 
 ### The `extraReducers` "map object" notation
 
+:::caution
+
+The "map object" notation is deprecated and will be removed in RTK 2.0. Please migrate to the "builder callback" notation, which offers much better TypeScript support and more flexibility. (There is [a "builder callback" codemod available to help with this migration](./codemods.mdx).)
+
+If you do not use the `builder callback` and are using TypeScript, you will need to use `actionCreator.type` or `actionCreator.toString()` to force the TS compiler to accept the computed property. Please see [Usage With TypeScript](./../usage/usage-with-typescript.md#type-safety-with-extraReducers) for further details.
+
+:::
+
 Like `reducers`, `extraReducers` can be an object containing Redux case reducer functions. However, the keys should
 be other Redux string action type constants, and `createSlice` will _not_ auto-generate action types or action creators
 for reducers included in this parameter.
@@ -185,12 +194,6 @@ createSlice({
 })
 ```
 
-:::tip
-
-We recommend using the `builder callback` API as the default, especially if you are using TypeScript. If you do not use the `builder callback` and are using TypeScript, you will need to use `actionCreator.type` or `actionCreator.toString()` to force the TS compiler to accept the computed property. Please see [Usage With TypeScript](./../usage/usage-with-typescript.md#type-safety-with-extraReducers) for further details.
-
-:::
-
 ## Return Value
 
 `createSlice` will return an object that looks like:
diff --git a/docs/api/matching-utilities.mdx b/docs/api/matching-utilities.mdx
@@ -31,9 +31,9 @@ All these matchers can either be called with one or more thunks as arguments, in
 A higher-order function that accepts one or more of:
 
 - `redux-toolkit` action creator functions such as the ones produced by:
-  - [`createAction`](./createAction)
-  - [`createSlice`](./createSlice#return-value)
-  - [`createAsyncThunk`](./createAsyncThunk#promise-lifecycle-actions)
+  - [`createAction`](./createAction.mdx)
+  - [`createSlice`](./createSlice.mdx#return-value)
+  - [`createAsyncThunk`](./createAsyncThunk.mdx#promise-lifecycle-actions)
 - type guard functions
 - custom action creator functions that have a `.match` property that is a type guard
 
@@ -45,7 +45,7 @@ Accepts the same inputs as `isAllOf` and will return a type guard function that
 
 ## `isAsyncThunkAction`
 
-A higher-order function that returns a type guard function that may be used to check whether an action was created by [`createAsyncThunk`](./createAsyncThunk).
+A higher-order function that returns a type guard function that may be used to check whether an action was created by [`createAsyncThunk`](./createAsyncThunk.mdx).
 
 ```ts title="isAsyncThunkAction usage"
 import { isAsyncThunkAction } from '@reduxjs/toolkit'
@@ -117,7 +117,7 @@ function handleRejectedAction(action: AnyAction) {
 
 ## `isRejectedWithValue`
 
-A higher-order function that returns a type guard function that may be used to check whether an action is a 'rejected' action creator from the `createAsyncThunk` promise lifecycle that was created by [`rejectWithValue`](./createAsyncThunk#handling-thunk-errors).
+A higher-order function that returns a type guard function that may be used to check whether an action is a 'rejected' action creator from the `createAsyncThunk` promise lifecycle that was created by [`rejectWithValue`](./createAsyncThunk.mdx#handling-thunk-errors).
 
 ```ts title="isRejectedWithValue usage"
 import { isRejectedWithValue } from '@reduxjs/toolkit'
@@ -145,10 +145,7 @@ we're able to easily use the same matcher for several cases in a type-safe manne
 First, let's examine an unnecessarily complex example:
 
 ```ts title="Example without using a matcher utility"
-import {
-  createAsyncThunk,
-  createReducer,
-} from '@reduxjs/toolkit'
+import { createAsyncThunk, createReducer } from '@reduxjs/toolkit'
 import type { PayloadAction } from '@reduxjs/toolkit'
 
 interface Data {
diff --git a/docs/rtk-query/usage/customizing-queries.mdx b/docs/rtk-query/usage/customizing-queries.mdx
@@ -26,6 +26,30 @@ See also [`baseQuery API Reference`](../api/createApi.mdx#basequery).
 
 RTK Query expects a `baseQuery` function to be called with three arguments: `args`, `api`, and `extraOptions`. It is expected to return an object with either a `data` or `error` property, or a promise that resolves to return such an object.
 
+:::tip
+
+Base query and query functions must _always_ catch errors themselves, and return it in an object!
+
+```ts no-transpile
+function brokenCustomBaseQuery() {
+  // ❌ Don't let this throw by itself
+  const data = await fetchSomeData()
+  return { data }
+}
+
+function correctCustomBaseQuery() {
+  // ✅ Catch errors and _return_ them so the RTKQ logic can track it
+  try {
+    const data = await fetchSomeData()
+    return { data }
+  } catch (error) {
+    return { error }
+  }
+}
+```
+
+:::
+
 #### baseQuery function arguments
 
 ```ts title="baseQuery example arguments" no-transpile
@@ -205,7 +229,11 @@ argument, which can be used while determining the transformed response. The valu
 dependent on the `baseQuery` used.
 
 ```ts title="transformErrorResponse meta example" no-transpile
-transformErrorResponse: (response: { data: { sideA: Tracks; sideB: Tracks } }, meta, arg) => {
+transformErrorResponse: (
+  response: { data: { sideA: Tracks; sideB: Tracks } },
+  meta,
+  arg
+) => {
   if (meta?.coinFlip === 'heads') {
     return response.data.sideA
   }
@@ -228,13 +256,17 @@ transformErrorResponse: (response: Posts, meta, arg) => {
 
 ## Customizing queries with `queryFn`
 
-Individual endpoints on [`createApi`](../api/createApi.mdx) accept a [`queryFn`](../api/createApi.mdx#queryfn) property which allows a given endpoint to ignore `baseQuery` for that endpoint by providing an inline function determining how that query resolves.
+RTK Query comes with `fetchBaseQuery` out of the box, which makes it straightforward to define endpoints that talk to HTTP URLs (such as a typical REST API). We also have integrations with GraphQL as well. However, at its core, RTK Query is really about tracking loading state and cached values for _any_ async request/response sequence, not just HTTP requests.
 
-This can be useful for scenarios where you want to have particularly different behaviour for a single endpoint, or where the query itself is not relevant. Such situations may include:
+RTK Query supports defining endpoints that run arbitrary async logic and return a result. Individual endpoints on [`createApi`](../api/createApi.mdx) accept a [`queryFn`](../api/createApi.mdx#queryfn) property, which let you write your own async function with whatever logic you want inside.
+
+This can be useful for scenarios where you want to have particularly different behaviour for a single endpoint, or where the query itself is not relevant, including:
 
 - One-off queries that use a different base URL
 - One-off queries that use different request handling, such as automatic re-tries
 - One-off queries that use different error handling behaviour
+- Queries that make requests using a third-party library SDK, such as Firebase or Supabase
+- Queries that perform async tasks that are not a typical request/response
 - Performing multiple requests with a single query ([example](#performing-multiple-requests-with-a-single-query))
 - Leveraging invalidation behaviour with no relevant query ([example](#using-a-no-op-queryfn))
 - Using [Streaming Updates](./streaming-updates) with no relevant initial request ([example](#streaming-data-with-no-initial-request))
@@ -243,7 +275,39 @@ See also [`queryFn API Reference`](../api/createApi.mdx#queryfn) for the type si
 
 ### Implementing a `queryFn`
 
-In order to use `queryFn`, it can be treated as an inline `baseQuery`. It will be called with the same arguments as `baseQuery`, as well as the provided `baseQuery` function itself (`arg`, `api`, `extraOptions`, and `baseQuery`). Similarly to `baseQuery`, it is expected to return an object with either a `data` or `error` property, or a promise that resolves to return such an object.
+A `queryFn` can be thought of as an inline `baseQuery`. It will be called with the same arguments as `baseQuery`, as well as the provided `baseQuery` function itself (`arg`, `api`, `extraOptions`, and `baseQuery`). Similarly to `baseQuery`, it is expected to return an object with either a `data` or `error` property, or a promise that resolves to return such an object.
+
+#### Basic `queryFn` Example
+
+```ts title="Basic queryFn example" no-transpile
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query'
+import { userAPI, User } from './userAPI'
+
+const api = createApi({
+  baseQuery: fetchBaseQuery({ url: '/' }),
+  endpoints: (build) => ({
+    // normal HTTP endpoint using fetchBaseQuery
+    getPosts: build.query<PostsResponse, void>({
+      query: () => ({ url: 'posts' }),
+    }),
+    // highlight-start
+    // endpoint with a custom `queryFn` and separate async logic
+    getUser: build.query<User, string>({
+      queryFn: async (userId: string) => {
+        try {
+          const user = await userApi.getUserById(userId)
+          // Return the result in an object with a `data` field
+          return { data: user }
+        } catch (error) {
+          // Catch any errors and return them as an object with an `error` field
+          return { error }
+        }
+      },
+    }),
+    // highlight-end
+  }),
+})
+```
 
 #### queryFn function arguments
 
@@ -318,7 +382,7 @@ const axiosBaseQuery =
       return {
         error: {
           status: err.response?.status,
-          data: err.response?.data || err.message
+          data: err.response?.data || err.message,
         },
       }
     }
@@ -610,10 +674,7 @@ In such a scenario, the return value would look like so:
 export declare const uuid: () => string
 
 // file: metaBaseQuery.ts
-import {
-  fetchBaseQuery,
-  createApi,
-} from '@reduxjs/toolkit/query'
+import { fetchBaseQuery, createApi } from '@reduxjs/toolkit/query'
 import type {
   BaseQueryFn,
   FetchArgs,
@@ -710,10 +771,7 @@ export interface Post {
 }
 
 // file: src/services/api.ts
-import {
-  createApi,
-  fetchBaseQuery,
-} from '@reduxjs/toolkit/query/react'
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
 import type {
   BaseQueryFn,
   FetchArgs,
@@ -880,6 +938,34 @@ export const { useGetPostsQuery } = api
 
 ## Examples - `queryFn`
 
+### Using a Third-Party SDK
+
+Many services like Firebase and Supabase provide their own SDK to make requests. You can use those SDK methods in a `queryFn`:
+
+```ts title="Basic Third-Party SDK" no-transpile
+import { createApi, fakeBaseQuery } from '@reduxjs/toolkit/query/react'
+import { supabase } from './supabaseApi'
+
+export const supabaseApi = createApi({
+  reducerPath: 'supabaseApi',
+  baseQuery: fakeBaseQuery(),
+  endpoints: (builder) => ({
+    getBlogs: builder.query({
+      queryFn: async () => {
+        // Supabase conveniently already has `data` and `error` fields
+        const { data, error } = await supabase.from('blogs').select()
+        if (error) {
+          return { error }
+        }
+        return { data }
+      },
+    }),
+  }),
+})
+```
+
+You could also try creating a custom base query that uses the SDK, and define endpoints that pass method names or args into that base query.
+
 ### Using a no-op queryFn
 
 In certain scenarios, you may wish to have a `query` or `mutation` where sending a request or returning data is not relevant for the situation. Such a scenario would be to leverage the `invalidatesTags` property to force re-fetch specific `tags` that have been provided to the cache.
@@ -987,10 +1073,7 @@ export interface User {
 }
 
 // file: api.ts
-import {
-  createApi,
-  fetchBaseQuery,
-} from '@reduxjs/toolkit/query'
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query'
 import type { FetchBaseQueryError } from '@reduxjs/toolkit/query'
 import type { Post, User } from './types'
 
@@ -1001,7 +1084,8 @@ const api = createApi({
       async queryFn(_arg, _queryApi, _extraOptions, fetchWithBQ) {
         // get a random user
         const randomResult = await fetchWithBQ('users/random')
-        if (randomResult.error) return { error: randomResult.error as FetchBaseQueryError } 
+        if (randomResult.error)
+          return { error: randomResult.error as FetchBaseQueryError }
         const user = randomResult.data as User
         const result = await fetchWithBQ(`user/${user.id}/posts`)
         return result.data
diff --git a/docs/rtk-query/usage/mutations.mdx b/docs/rtk-query/usage/mutations.mdx
@@ -24,6 +24,8 @@ If the `query` callback needs additional data to generate the URL, it should be
 
 Mutation endpoints may also modify the response contents before the result is cached, define "tags" to identify cache invalidation, and provide cache entry lifecycle callbacks to run additional logic as cache entries are added and removed.
 
+When used with TypeScript, you should supply generics for the return type and the expected query argument: `build.mutation<ReturnType, ArgType>`. If there is no argument, use `void` for the arg type instead.
+
 ```ts title="Example of all mutation endpoint options"
 // file: types.ts noEmit
 export interface Post {
@@ -41,6 +43,7 @@ const api = createApi({
   }),
   tagTypes: ['Post'],
   endpoints: (build) => ({
+    // The mutation accepts a `Partial<Post>` arg, and returns a `Post`
     updatePost: build.mutation<Post, Partial<Post> & Pick<Post, 'id'>>({
       // highlight-start
       // note: an optional `queryFn` may be used in place of `query`
diff --git a/docs/rtk-query/usage/queries.mdx b/docs/rtk-query/usage/queries.mdx
@@ -34,6 +34,8 @@ If the `query` callback needs additional data to generate the URL, it should be
 
 Query endpoints may also modify the response contents before the result is cached, define "tags" to identify cache invalidation, and provide cache entry lifecycle callbacks to run additional logic as cache entries are added and removed.
 
+When used with TypeScript, you should supply generics for the return type and the expected query argument: `build.query<ReturnType, ArgType>`. If there is no argument, use `void` for the arg type instead.
+
 ```ts title="Example of all query endpoint options"
 // file: types.ts noEmit
 export interface Post {
@@ -52,8 +54,9 @@ const api = createApi({
   }),
   tagTypes: ['Post'],
   endpoints: (build) => ({
+    // highlight-start
+    // The query accepts a number and returns a Post
     getPost: build.query<Post, number>({
-      // highlight-start
       // note: an optional `queryFn` may be used in place of `query`
       query: (id) => ({ url: `post/${id}` }),
       // Pick out data and prevent nested properties in a hook or selector
diff --git a/docs/usage/usage-with-typescript.md b/docs/usage/usage-with-typescript.md
