Merge pull request #3909 from reduxjs/feature/2.0-docs-cleanup

Author: markerikson

docs/api/createSlice.mdx

@@ -304,16 +304,25 @@ Typing for the `create.asyncThunk` works in the same way as [`createAsyncThunk`]
 
 A type for `state` and/or `dispatch` _cannot_ be provided as part of the `ThunkApiConfig`, as this would cause circular types.
 
-Instead, it is necessary to assert the type when needed.
+Instead, it is necessary to assert the type when needed - `getState() as RootState`. You may also include an explicit return type for the payload function as well, in order to break the circular type inference cycle.
 
 ```ts no-transpile
 create.asyncThunk<Todo, string, { rejectValue: { error: string } }>(
-  async (id, thunkApi) => {
+  // highlight-start
+  // may need to include an explicit return type
+  async (id: string, thunkApi): Promise<Todo> => {
+    // Cast types for `getState` and `dispatch` manually
     const state = thunkApi.getState() as RootState
     const dispatch = thunkApi.dispatch as AppDispatch
-    throw thunkApi.rejectWithValue({
-      error: 'Oh no!',
-    })
+    // highlight-end
+    try {
+      const todo = await fetchTodo()
+      return todo
+    } catch (e) {
+      throw thunkApi.rejectWithValue({
+        error: 'Oh no!',
+      })
+    }
   }
 )
 ```

docs/api/getDefaultMiddleware.mdx

@@ -55,7 +55,7 @@ const store = configureStore({
 // Store has all of the default middleware added, _plus_ the logger middleware
 ```
 
-It is preferable to use the chainable `.concat(...)` and `.prepend(...)` methods of the returned `Tuple` instead of the array spread operator, as the latter can lose valuable type information under some circumstances.
+It is preferable to use the chainable `.concat(...)` and `.prepend(...)` methods of the returned `Tuple` instead of the array spread operator, as the latter can lose valuable TS type information under some circumstances.
 
 ## Included Default Middleware
 

docs/introduction/getting-started.md

@@ -34,7 +34,7 @@ you make your Redux code better.
 
 ### Create a React Redux App
 
-The recommended way to start new apps with React and Redux is by using [our official Redux+TS template for Vite](https://github.com/reduxjs/redux-templates), or by creating a new Next.js project using [Next's `with-redux` template](https://github.com/vercel/next.js/tree/canary/examples/with-redux).
+The recommended way to start new apps with React and Redux Toolkit is by using [our official Redux Toolkit + TS template for Vite](https://github.com/reduxjs/redux-templates), or by creating a new Next.js project using [Next's `with-redux` template](https://github.com/vercel/next.js/tree/canary/examples/with-redux).
 
 Both of these already have Redux Toolkit and React-Redux configured appropriately for that build tool, and come with a small example app that demonstrates how to use several of Redux Toolkit's features.
 
@@ -85,8 +85,7 @@ yarn add react-redux
   </TabItem>
 </Tabs>
 
-It is also available as a precompiled UMD package that defines a `window.RTK` global variable.
-The UMD package can be used as a [`<script>` tag](https://unpkg.com/@reduxjs/toolkit/dist/redux-toolkit.umd.js) directly.
+The package includes a precompiled ESM build that can be used as a [`<script type="module">` tag](https://unpkg.com/@reduxjs/toolkit/dist/redux-toolkit.browser.mjs) directly in the browser.
 
 ## What's Included
 

docs/migrations/1.x-to-2.x.md

@@ -12,15 +12,23 @@ toc_max_heading_level: 4
 
 # Migrating 1.x → 2.x
 
+:::tip What You'll Learn
+
+- What's changed in Redux Toolkit 2.0 and Redux core 5.0, including breaking changes and new features
+
+:::
+
 ## Introduction
 
 Redux Toolkit has been available since 2019, and today it's the standard way to write Redux apps. We've gone 4+ years without any breaking changes. Now, RTK 2.0 gives us a chance to modernize the packaging, clean up deprecated options, and tighten up some edge cases.
 
 Redux Toolkit 2.0 is accompanied by major versions of all the other Redux packages: Redux core 5.0, React-Redux 9.0, Redux Thunk 3.0, and Reselect 5.0.
 
-This page lists known potentially breaking changes in Redux Toolkit 2.0 and Redux core 5.0, as well as new features in Redux Toolkit 2.0. As a reminder, you should not need to actually install or use the core `redux` package directly - RTK wraps that, and re-exports all methods and types.
+This page lists known potentially breaking changes in Redux Toolkit 2.0 and Redux core 5.0, as well as new features in Redux Toolkit 2.0. As a reminder, **you should not need to actually install or use the core `redux` package directly** - RTK wraps that, and re-exports all methods and types.
+
+In practice, **most of the "breaking" changes should not have an actual effect on end users, and we expect that many projects can just update the package versions with very few code changes needed**.
 
-In practice, **most of the "breaking" changes should not have an actual effect on end users**. The changes most likely to need app code updates are:
+The changes most likely to need app code updates are:
 
 - [Object syntax removed for `createReducer` and `createSlice.extraReducers`](#object-syntax-for-createsliceextrareducers-and-createreducer-removed)
 - [`configureStore.middleware` must be a callback](#configurestoremiddleware-must-be-a-callback)
@@ -66,6 +74,20 @@ We've always specifically told our users that [actions and state _must_ be seria
 
 In practice, this was already true 99.99% of the time and shouldn't have any effect on users (especially those using Redux Toolkit and `createSlice`), but there may be some legacy Redux codebases that opted to use Symbols as action types.
 
+#### `createStore` Deprecation
+
+In [Redux 4.2.0, we marked the original `createStore` method as `@deprecated`](https://github.com/reduxjs/redux/releases/tag/v4.2.0). Strictly speaking, **this is _not_ a breaking change**, nor is it new in 5.0, but we're documenting it here for completeness.
+
+**This deprecation is solely a _visual_ indicator that is meant to encourage users to [migrate their apps from legacy Redux patterns to use the modern Redux Toolkit APIs](https://redux.js.org/usage/migrating-to-modern-redux)**. The deprecation results in a visual strikethrough when imported and used, like ~~`createStore`~~, but with _no_ runtime errors or warnings.
+
+**`createStore` will continue to work indefinitely, and will _not_ ever be removed**. But, today we want _all_ Redux users to be using Redux Toolkit for all of their Redux logic.
+
+To fix this, there are three options:
+
+- **[Follow our strong suggestion to switch over to Redux Toolkit and `configureStore`](https://redux.js.org/usage/migrating-to-modern-redux)**
+- Do nothing. It's just a visual strikethrough, and it doesn't affect how your code behaves. Ignore it.
+- Switch to using the `legacy_createStore` API that is now exported, which is the exact same function but with no `@deprecated` tag. The simplest option is to do an aliased import rename, like `import { legacy_createStore as createStore } from 'redux'`
+
 <div class="typescript-only">
 
 #### Typescript rewrite
@@ -78,6 +100,26 @@ Redux core v5 is now built from that TS-converted source code. In theory, this s
 
 Please report any unexpected compatibility issues on [Github](https://github.com/reduxjs/redux/issues)!
 
+#### `AnyAction` deprecated in favour of `UnknownAction`
+
+The Redux TS types have always exported an `AnyAction` type, which is defined to have `{type: string}` and treat any other field as `any`. This makes it easy to write uses like `console.log(action.whatever)`, but unfortunately does not provide any meaningful type safety.
+
+We now export an `UnknownAction` type, which treats all fields other than `action.type` as `unknown`. This encourages users to write type guards that check the action object and assert its _specific_ TS type. Inside of those checks, you can access a field with better type safety.
+
+`UnknownAction` is now the default any place in the Redux source that expects an action object.
+
+`AnyAction` still exists for compatibility, but has been marked as deprecated.
+
+Note that [Redux Toolkit's action creators have a `.match()` method](https://redux-toolkit.js.org/api/createAction#actioncreatormatch) that acts as a useful type guard:
+
+```ts
+if (todoAdded.match(someUnknownAction)) {
+  // action is now typed as a PayloadAction<Todo>
+}
+```
+
+You can also use the new `isAction` util to check if an unknown value is some kind of action object.
+
 #### `Middleware` type changed - Middleware `action` and `next` are typed as `unknown`
 
 Previously, the `next` parameter is typed as the `D` type parameter passed, and `action` is typed as the `Action` extracted from the dispatch type. Neither of these are a safe assumption:
@@ -88,6 +130,8 @@ Previously, the `next` parameter is typed as the `D` type parameter passed, and
 
 We've changed `next` to be `(action: unknown) => unknown` (which is accurate, we have no idea what `next` expects or will return), and changed the `action` parameter to be `unknown` (which as above, is accurate).
 
+In order to safely interact with values or access fields inside of the `action` argument, you must first do a type guard check to narrow the type, such as `isAction(action)` or `someActionCreator.match(action)`.
+
 This new type is incompatible with the v4 `Middleware` type, so if a package's middleware is saying it's incompatible, check which version of Redux it's getting its types from!
 
 #### `PreloadedState` type removed in favour of `Reducer` generic
@@ -119,24 +163,6 @@ This change does include some breaking changes, but overall should not have a hu
 - The overloads for `combineReducers` are removed in favor of a single function definition that takes the `ReducersMapObject` as its generic parameter. Removing the overloads was necessary with these changes, since sometimes it was choosing the wrong overload.
 - Enhancers that explicitly list the generics for the reducer will need to add the third generic.
 
-#### `AnyAction` deprecated in favour of `UnknownAction`
-
-The Redux TS types have always exported an `AnyAction` type, which is defined to have `{type: string}` and treat any other field as `any`. This makes it easy to write uses like `console.log(action.whatever)`, but unfortunately does not provide any meaningful type safety.
-
-We now export an `UnknownAction` type, which treats all fields other than `action.type` as `unknown`. This encourages users to write type guards that check the action object and assert its _specific_ TS type. Inside of those checks, you can access a field with better type safety.
-
-`UnknownAction` is now the default any place in the Redux source that expects an action object.
-
-`AnyAction` still exists for compatibility, but has been marked as deprecated.
-
-Note that [Redux Toolkit's action creators have a `.match()` method](https://redux-toolkit.js.org/api/createAction#actioncreatormatch) that acts as a useful type guard:
-
-```ts
-if (todoAdded.match(someUnknownAction)) {
-  // action is now typed as a PayloadAction<Todo>
-}
-```
-
 </div>
 
 ### Toolkit only
@@ -499,11 +525,11 @@ In practice, we hope these are reasonable tradeoffs. Creating thunks inside of `
 Here's what the new callback syntax looks like:
 
 ```ts
-const createSlice = buildCreateSlice({
+const createSliceWithThunks = buildCreateSlice({
   creators: { asyncThunk: asyncThunkCreator },
 })
 
-const todosSlice = createSlice({
+const todosSlice = createSliceWithThunks({
   name: 'todos',
   initialState: {
     loading: false,

docs/rtk-query/usage-with-typescript.mdx

@@ -390,6 +390,32 @@ const api = createApi({
 })
 ```
 
+### Typing `dispatch` and `getState`
+
+`createApi` exposes the standard Redux `dispatch` and `getState` methods in several places, such as the `lifecycleApi` argument in lifecycle methods, or the `baseQueryApi` argument passed to `queryFn` methods and base query functions.
+
+Normally, [your application infers `RootState` and `AppDispatch` types from the store setup](../tutorials/typescript.md#define-root-state-and-dispatch-types). Since `createApi` has to be called prior to creating the Redux store and is used as part of the store setup sequence, it can't directly know or use those types - it would cause a circular type inference error.
+
+By default, `dispatch` usages inside of `createApi` will be typed as `ThunkDispatch`, and `getState` usages are typed as `() => unknown`. You will need to assert the type when needed - `getState() as RootState`. You may also include an explicit return type for the function as well, in order to break the circular type inference cycle:
+
+```ts no-transpile
+const api = createApi({
+  baseQuery,
+  endpoints: (build) => ({
+    getTodos: build.query<Todo[], void>({
+      async queryFn() {
+        // highlight-start
+        // Cast state as `RootState`
+        const state = getState() as RootState
+        // highlight-end
+        const text = state.todoTexts[queryFnCalls]
+        return { data: [{ id: `${queryFnCalls++}`, text }] }
+      },
+    }),
+  }),
+})
+```
+
 ### Typing `providesTags`/`invalidatesTags`
 
 RTK Query utilizes a cache tag invalidation system in order to provide [automated re-fetching](./usage/automated-refetching.mdx) of stale data.

docs/rtk-query/usage/customizing-queries.mdx

@@ -376,7 +376,13 @@ const axiosBaseQuery =
   > =>
   async ({ url, method, data, params, headers }) => {
     try {
-      const result = await axios({ url: baseUrl + url, method, data, params, headers })
+      const result = await axios({
+        url: baseUrl + url,
+        method,
+        data,
+        params,
+        headers,
+      })
       return { data: result.data }
     } catch (axiosError) {
       const err = axiosError as AxiosError
@@ -608,7 +614,7 @@ The `retry` utility has a `fail` method property attached which can be used to b
 
 ```ts title="Bailing out of error re-tries"
 import { createApi, fetchBaseQuery, retry } from '@reduxjs/toolkit/query/react'
-import type { FetchArgs } from '@reduxjs/toolkit/dist/query/fetchBaseQuery'
+import type { FetchArgs } from '@reduxjs/toolkit/query'
 interface Post {
   id: number
   name: string

docs/usage/usage-with-typescript.md

@@ -326,9 +326,9 @@ const blogSlice = createSlice({
 
 ### Generated Action Types for Slices
 
-As TS cannot combine two string literals (`slice.name` and the key of `actionMap`) into a new literal, all actionCreators created by `createSlice` are of type 'string'. This is usually not a problem, as these types are only rarely used as literals.
+`createSlice` generates action type strings by combining the `name` field from the slice with the field name of the reducer function, like `'test/increment'`. This is strongly typed as the exact value, thanks to TS's string literal analysis.
 
-In most cases that `type` would be required as a literal, the `slice.action.myAction.match` [type predicate](https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates) should be a viable alternative:
+You can also use the `slice.action.myAction.match` [type predicate](https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates) should be a viable alternative:
 
 ```ts {10}
 const slice = createSlice({
@@ -339,6 +339,9 @@ const slice = createSlice({
   },
 })
 
+type incrementType = typeof slice.actions.increment.type
+// type incrementType = 'test/increment'
+
 function myCustomMiddleware(action: Action) {
   if (slice.actions.increment.match(action)) {
     // `action` is narrowed down to the type `PayloadAction<number>` here.
@@ -408,6 +411,59 @@ type AtLeastOne<T extends Record<string, any>> = keyof T extends infer K
 type AtLeastOneUserField = AtLeastOne<User>
 ```
 
+### Typing Async Thunks Inside `createSlice`
+
+As of 2.0, `createSlice` allows [defining thunks inside of `reducers` using a callback syntax](../api/createSlice.mdx/#the-reducers-creator-callback-notation).
+
+Typing for the `create.asyncThunk` method works in the same way as [`createAsyncThunk`](#createasyncthunk), with one key difference.
+
+A type for `state` and/or `dispatch` _cannot_ be provided as part of the `ThunkApiConfig`, as this would cause circular types.
+
+Instead, it is necessary to assert the type when needed - `getState() as RootState`. You may also include an explicit return type for the payload function as well, in order to break the circular type inference cycle.
+
+```ts no-transpile
+create.asyncThunk<Todo, string, { rejectValue: { error: string } }>(
+  // highlight-start
+  // may need to include an explicit return type
+  async (id: string, thunkApi): Promise<Todo> => {
+    // Cast types for `getState` and `dispatch` manually
+    const state = thunkApi.getState() as RootState
+    const dispatch = thunkApi.dispatch as AppDispatch
+    // highlight-end
+    try {
+      const todo = await fetchTodo()
+      return todo
+    } catch (e) {
+      throw thunkApi.rejectWithValue({
+        error: 'Oh no!',
+      })
+    }
+  }
+)
+```
+
+For common thunk API configuration options, a [`withTypes` helper](../usage/usage-with-typescript#defining-a-pre-typed-createasyncthunk) is provided:
+
+```ts no-transpile
+reducers: (create) => {
+  const createAThunk =
+    create.asyncThunk.withTypes<{ rejectValue: { error: string } }>()
+
+  return {
+    fetchTodo: createAThunk<Todo, string>(async (id, thunkApi) => {
+      throw thunkApi.rejectWithValue({
+        error: 'Oh no!',
+      })
+    }),
+    fetchTodos: createAThunk<Todo[], string>(async (id, thunkApi) => {
+      throw thunkApi.rejectWithValue({
+        error: 'Oh no, not again!',
+      })
+    }),
+  }
+}
+```
+
 ### Wrapping `createSlice`
 
 If you need to reuse reducer logic, it is common to write ["higher-order reducers"](https://redux.js.org/recipes/structuring-reducers/reusing-reducer-logic#customizing-behavior-with-higher-order-reducers) that wrap a reducer function with additional common behavior. This can be done with `createSlice` as well, but due to the complexity of the types for `createSlice`, you have to use the `SliceCaseReducers` and `ValidateSliceCaseReducers` types in a very specific way.