Assorted docs tweaks (#932)

- Updated Immer docs URLs
- Made TS examples consistent with other sites
- Added `no-param-reassign` section in "Immer Reducers" page

Author: markerikson

docs/api/createReducer.mdx

@@ -219,7 +219,7 @@ const todosReducer = createReducer([] as Todo[], builder => {
 })
 ```
 
-Writing "mutating" reducers simplifies the code. It's shorter, there's less indirection, and it eliminates common mistakes made while spreading nested state. However, the use of Immer does add some "magic", and Immer has its own nuances in behavior. You should read through [pitfalls mentioned in the immer docs](https://immerjs.github.io/immer/docs/pitfalls) . Most importantly, **you need to ensure that you either mutate the `state` argument or return a new state, _but not both_**. For example, the following reducer would throw an exception if a `toggleTodo` action is passed:
+Writing "mutating" reducers simplifies the code. It's shorter, there's less indirection, and it eliminates common mistakes made while spreading nested state. However, the use of Immer does add some "magic", and Immer has its own nuances in behavior. You should read through [pitfalls mentioned in the immer docs](https://immerjs.github.io/immer/pitfalls) . Most importantly, **you need to ensure that you either mutate the `state` argument or return a new state, _but not both_**. For example, the following reducer would throw an exception if a `toggleTodo` action is passed:
 
 ```ts
 import { createAction, createReducer } from '@reduxjs/toolkit'
@@ -289,7 +289,7 @@ console.log(reducer(0, { type: 'increment' }))
 
 It's very common for a developer to call `console.log(state)` during the development process. However, browsers display Proxies in a format that is hard to read, which can make console logging of Immer-based state difficult.
 
-When using either `createSlice` or `createReducer`, you may use the [`current`](./otherExports.mdx#current) utility that we re-export from the [`immer` library](https://immerjs.github.io/immer/docs/current). This utility creates a separate plain copy of the current Immer `Draft` state value, which can then be logged for viewing as normal.
+When using either `createSlice` or `createReducer`, you may use the [`current`](./otherExports.mdx#current) utility that we re-export from the [`immer` library](https://immerjs.github.io/immer/current). This utility creates a separate plain copy of the current Immer `Draft` state value, which can then be logged for viewing as normal.
 
 ```ts
 import { createSlice, current } from '@reduxjs/toolkit'

docs/api/otherExports.mdx

@@ -24,15 +24,15 @@ console.log(nanoid())
 
 ### `createNextState`
 
-The default immutable update function from the [`immer` library](https://immerjs.github.io/immer/), re-exported here as `createNextState` (also commonly referred to as [`produce`](https://immerjs.github.io/immer/docs/produce))
+The default immutable update function from the [`immer` library](https://immerjs.github.io/immer/), re-exported here as `createNextState` (also commonly referred to as [`produce`](https://immerjs.github.io/immer/produce))
 
 ### `current`
 
-[The `current` function](https://immerjs.github.io/immer/docs/current) from the [`immer` library](https://immerjs.github.io/immer/), which takes a snapshot of the current state of a draft and finalizes it (but without freezing). Current is a great utility to print the current state during debugging, and the output of `current` can also be safely leaked outside the producer.
+[The `current` function](https://immerjs.github.io/immer/current) from the [`immer` library](https://immerjs.github.io/immer/), which takes a snapshot of the current state of a draft and finalizes it (but without freezing). Current is a great utility to print the current state during debugging, and the output of `current` can also be safely leaked outside the producer.
 
 ### `original`
 
-[The `original` function](https://immerjs.github.io/immer/docs/original) from the [`immer` library](https://immerjs.github.io/immer/), which returns the original object. This is particularly useful for referential equality check in reducers.
+[The `original` function](https://immerjs.github.io/immer/original) from the [`immer` library](https://immerjs.github.io/immer/), which returns the original object. This is particularly useful for referential equality check in reducers.
 
 ```ts
 import { createReducer, createAction, current } from '@reduxjs/toolkit'

docs/tutorials/quick-start.md

@@ -86,7 +86,7 @@ Add a new file named `src/features/counter/counterSlice.js`. In that file, impor
 
 Creating a slice requires a string name to identify the slice, an initial state value, and one or more reducer functions to define how the state can be updated. Once a slice is created, we can export the generated Redux action creators and the reducer function for the whole slice.
 
-Redux requires that [we write all state updates immutably, by making copies of data and updating the copies](https://redux.js.org/tutorials/fundamentals/part-2-concepts-data-flow#immutability). However, Redux Toolkit's `createSlice` and `createReducer` APIs use [Immer](https://immerjs.github.io/immer/docs/introduction) inside to allow us to [write "mutating" update logic that becomes correct immutable updates](https://redux.js.org/tutorials/fundamentals/part-8-modern-redux#immutable-updates-with-immer).
+Redux requires that [we write all state updates immutably, by making copies of data and updating the copies](https://redux.js.org/tutorials/fundamentals/part-2-concepts-data-flow#immutability). However, Redux Toolkit's `createSlice` and `createReducer` APIs use [Immer](https://immerjs.github.io/immer/introduction) inside to allow us to [write "mutating" update logic that becomes correct immutable updates](https://redux.js.org/tutorials/fundamentals/part-8-modern-redux#immutable-updates-with-immer).
 
 ```js title="features/counter/counterSlice.js"
 import { createSlice } from '@reduxjs/toolkit'

docs/tutorials/typescript.md

@@ -43,25 +43,32 @@ import { configureStore } from '@reduxjs/toolkit'
 
 const store = configureStore({
   reducer: {
-    one: oneSlice.reducer,
-    two: twoSlice.reducer
+    posts: postsReducer,
+    comments: commentsReducer,
+    users: usersReducer
   }
 })
 
 // highlight-start
 // Infer the `RootState` and `AppDispatch` types from the store itself
 export type RootState = ReturnType<typeof store.getState>
+// Inferred type: {posts: PostsState, comments: CommentsState, users: UsersState}
 export type AppDispatch = typeof store.dispatch
 // highlight-end
 ```
 
 ### Define Typed Hooks
 
-While it's possible to import the `RootState` and `AppDispatch` types into each component, it's better to create typed versions of the `useDispatch` and `useSelector` hooks for usage in your application. Since these are actual variables, not types, it's important to define them in a separate file such as `app/hooks.ts`, not the store setup file. This allows you to import them into any component file that needs to use the hooks, and avoids potential circular import dependency issues.
+While it's possible to import the `RootState` and `AppDispatch` types into each component, it's **better to create typed versions of the `useDispatch` and `useSelector` hooks for usage in your application**. . This is important for a couple reasons:
+
+- For `useSelector`, it saves you the need to type `(state: RootState)` every time
+- For `useDispatch`, the default `Dispatch` type does not know about thunks. In order to correctly dispatch thunks, you need to use the specific customized `AppDispatch` type from the store that includes the thunk middleware types, and use that with `useDispatch`. Adding a pre-typed `useDispatch` hook keeps you from forgetting to import `AppDispatch` where it's needed.
+
+Since these are actual variables, not types, it's important to define them in a separate file such as `app/hooks.ts`, not the store setup file. This allows you to import them into any component file that needs to use the hooks, and avoids potential circular import dependency issues.
 
 ```ts title="app/hooks.ts"
 import { TypedUseSelectorHook, useDispatch, useSelector } from 'react-redux'
-import { RootState, AppDispatch } from './store'
+import type { RootState, AppDispatch } from './store'
 
 // highlight-start
 // Use throughout your app instead of plain `useDispatch` and `useSelector`
@@ -82,7 +89,7 @@ You can safely import the `RootState` type from the store file here. It's a circ
 
 ```ts title="features/counter/counterSlice.ts"
 import { createSlice, PayloadAction } from '@reduxjs/toolkit'
-import { RootState } from '../../app/store'
+import type { RootState } from '../../app/store'
 
 // highlight-start
 // Define a type for the slice state
@@ -124,6 +131,17 @@ export const selectCount = (state: RootState) => state.counter.value
 export default counterSlice.reducer
 ```
 
+The generated action creators will be correctly typed to accept a `payload` argument based on the `PayloadAction<T>` type you provided for the reducer. For example, `incrementByAmount` requires a `number` as its argument.
+
+In some cases, [TypeScript may unnecessarily tighten the type of the initial state](https://github.com/reduxjs/redux-toolkit/pull/827). If that happens, you can work around it by casting the initial state using `as`, instead of declaring the type of the variable:
+
+```ts
+// Workaround: cast state instead of declaring variable type
+const initialState = {
+  value: 0
+} as CounterState
+```
+
 ### Use Typed Hooks in Components
 
 In component files, import the pre-typed hooks instead of the standard hooks from React-Redux.

docs/usage/immer-reducers.md

@@ -7,7 +7,7 @@ hide_title: true
 
 # Writing Reducers with Immer
 
-Redux Toolkit's [`createReducer`](../api/createReducer.mdx) and [`createSlice`](../api/createSlice.mdx) automatically use [Immer](https://immerjs.github.io/immer/docs/introduction) internally to let you write simpler immutable update logic using "mutating" syntax. This helps simplify most reducer implementations.
+Redux Toolkit's [`createReducer`](../api/createReducer.mdx) and [`createSlice`](../api/createSlice.mdx) automatically use [Immer](https://immerjs.github.io/immer/introduction) internally to let you write simpler immutable update logic using "mutating" syntax. This helps simplify most reducer implementations.
 
 Because Immer is itself an abstraction layer, it's important to understand why Redux Toolkit uses Immer, and how to use it correctly.
 
@@ -143,7 +143,7 @@ Writing immutable update logic by hand _is_ hard, and **accidentally mutating st
 
 ## Immutable Updates with Immer
 
-[Immer](https://immerjs.github.io/immer/docs/introduction) is a library that simplifies the process of writing immutable update logic.
+[Immer](https://immerjs.github.io/immer/introduction) is a library that simplifies the process of writing immutable update logic.
 
 Immer provides a function called `produce`, which accepts two arguments: your original `state`, and a callback function. The callback function is given a "draft" version of that state, and inside the callback, it is safe to write code that mutates the draft value. Immer tracks all attempts to mutate the draft value and then replays those mutations using their immutable equivalents to create a safe, immutably updated result:
 
@@ -363,7 +363,7 @@ It's common to want to log in-progress state from a reducer to see what it looks
 
 ![Logged proxy draft](/img/usage/immer-reducers/logged-proxy.png)
 
-To work around this, [Immer includes a `current` function that extracts a copy of the wrapped data](https://immerjs.github.io/immer/docs/current), and RTK re-exports `current`. You can use this in your reducers if you need to log or inspect the work-in-progress state:
+To work around this, [Immer includes a `current` function that extracts a copy of the wrapped data](https://immerjs.github.io/immer/current), and RTK re-exports `current`. You can use this in your reducers if you need to log or inspect the work-in-progress state:
 
 ```js
 import { current } from '@reduxjs/toolkit'
@@ -386,7 +386,7 @@ The correct output would look like this instead:
 
 ![Logged current value](/img/usage/immer-reducers/logged-current-state.png)
 
-Immer also provides [`original` and `isDraft` functions](https://immerjs.github.io/immer/docs/original), which retrieves the original data without any updates applied and check to see if a given value is a Proxy-wrapped draft. As of RTK 1.5.0, neither of those is re-exported - you'll need to specifically import them from `immer` yourself. We may re-export them from RTK in an upcoming release.
+Immer also provides [`original` and `isDraft` functions](https://immerjs.github.io/immer/original), which retrieves the original data without any updates applied and check to see if a given value is a Proxy-wrapped draft. As of RTK 1.5.0, neither of those is re-exported - you'll need to specifically import them from `immer` yourself. We may re-export them from RTK in an upcoming release.
 
 ### Updating Nested Data
 
@@ -418,7 +418,7 @@ const todosSlice = createSlice({
 })
 ```
 
-There _is_ a gotcha here. [Immer will not wrap objects that are newly inserted into the state](https://immerjs.github.io/immer/docs/pitfalls#data-not-originating-from-the-state-will-never-be-drafted). Most of the time this shouldn't matter, but there may be occasions when you want to insert a value and then make further updates to it.
+There _is_ a gotcha here. [Immer will not wrap objects that are newly inserted into the state](https://immerjs.github.io/immer/pitfalls#data-not-originating-from-the-state-will-never-be-drafted). Most of the time this shouldn't matter, but there may be occasions when you want to insert a value and then make further updates to it.
 
 Related to this, RTK's [`createEntityAdapter` update functions](../api/createEntityAdapter.mdx#crud-functions) can either be used as standalone reducers, or "mutating" update functions. These functions determine whether to "mutate" or return a new value by checking to see if the state they're given is wrapped in a draft or not. If you are calling these functions yourself inside of a case reducer, be sure you know whether you're passing them a draft value or a plain value.
 
@@ -447,6 +447,19 @@ const itemsSlice = createSlice({
 })
 ```
 
+### Linting State Mutations
+
+Many ESLint configs include the https://eslint.org/docs/rules/no-param-reassign rule, which may also warn about mutations to nested fields. That can cause the rule to warn about mutations to `state` in Immer-powered reducers, which is not helpful.
+
+To resolve this, you can tell the ESLint rule to ignore mutations to a parameter named `state`:
+
+```js
+{
+  'no-param-reassign': ['error', { props: true, ignorePropertyModificationsFor: ['state'] }]
+}
+
+```
+
 ## Further Information
 
 See [the Immer documentation](https://immerjs.github.io/immer/) for more details on Immer's APIs, edge cases, and behavior.

docs/usage/usage-with-typescript.md

@@ -19,7 +19,7 @@ Redux Toolkit is written in TypeScript, and its API is designed to enable great
 
 This page provides specific details for each of the different APIs included in Redux Toolkit and how to type them correctly with TypeScript.
 
-**See the [TypeScript Quick Start tutorial page](../tutorials/typescript.md) for a brief overview of how to set up and use Redux Toolkit and React-Redux to work with TypeScript**.
+**See the [TypeScript Quick Start tutorial page](../tutorials/typescript.md) for a brief overview of how to set up and use Redux Toolkit and React Redux to work with TypeScript**.
 
 :::info
 
@@ -132,9 +132,9 @@ configureStore({
 })
 ```
 
-### Using the extracted `Dispatch` type with React-Redux
+### Using the extracted `Dispatch` type with React Redux
 
-By default, the React-Redux `useDispatch` hook does not contain any types that take middlewares into account. If you need a more specific type for the `dispatch` function when dispatching, you may specify the type of the returned `dispatch` function, or create a custom-typed version of `useSelector`. See [the React-Redux documentation](https://react-redux.js.org/using-react-redux/static-typing#typing-the-usedispatch-hook) for details.
+By default, the React Redux `useDispatch` hook does not contain any types that take middlewares into account. If you need a more specific type for the `dispatch` function when dispatching, you may specify the type of the returned `dispatch` function, or create a custom-typed version of `useSelector`. See [the React Redux documentation](https://react-redux.js.org/using-react-redux/static-typing#typing-the-usedispatch-hook) for details.
 
 ## `createAction`
 
@@ -166,7 +166,7 @@ createAction('test', withPayloadType<string>())
 
 If you are using `action.type` as a discriminator on a discriminated union, for example to correctly type your payload in `case` statements, you might be interested in this alternative:
 
-Created action creators have a `match` method that acts as a [type predicate](https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates):
+Created action creators have a `match` method that acts as a [type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates):
 
 ```typescript
 const increment = createAction<number>('increment')
@@ -265,7 +265,7 @@ slice.actions.increment(2)
 slice.caseReducers.increment(0, { type: 'increment', payload: 5 })
 ```
 
-If you have too many reducers and defining them inline would be messy, you can also define them outside the `createSlice` call and type them as `CaseReducer`:
+If you have too many case reducers and defining them inline would be messy, or you want to reuse case reducers across slices, you can also define them outside the `createSlice` call and type them as `CaseReducer`:
 
 ```typescript
 type State = number
@@ -469,17 +469,20 @@ In the most common use cases, you should not need to explicitly declare any type
 Just provide a type for the first argument to the `payloadCreator` argument as you would for any function argument, and the resulting thunk will accept the same type as its input parameter.
 The return type of the `payloadCreator` will also be reflected in all generated action types.
 
-```ts {8,11,18}
+```ts
 interface MyData {
   // ...
 }
 
 const fetchUserById = createAsyncThunk(
   'users/fetchById',
+  // highlight-start
   // Declare the type your function argument here:
   async (userId: number) => {
+    // highlight-end
     const response = await fetch(`https://reqres.in/api/users/${userId}`)
     // Inferred return type: Promise<MyData>
+    // highlight-next-line
     return (await response.json()) as MyData
   }
 )
@@ -496,17 +499,20 @@ To define the types for these arguments, pass an object as the third generic arg
 
 ```ts
 const fetchUserById = createAsyncThunk<
+  // highlight-start
   // Return type of the payload creator
   MyData,
   // First argument to the payload creator
   number,
   {
+    // Optional fields for defining thunkApi field types
     dispatch: AppDispatch
     state: State
     extra: {
       jwt: string
     }
   }
+  // highlight-end
 >('users/fetchById', async (userId, thunkApi) => {
   const response = await fetch(`https://reqres.in/api/users/${userId}`, {
     headers: {
@@ -616,13 +622,14 @@ Typing `createEntityAdapter` only requires you to specify the entity type as the
 
 The example from the `createEntityAdapter` documentation would look like this in TypeScript:
 
-```ts {7}
+```ts
 interface Book {
   bookId: number
   title: string
   // ...
 }
 
+// highlight-next-line
 const booksAdapter = createEntityAdapter<Book>({
   selectId: book => book.bookId,
   sortComparer: (a, b) => a.title.localeCompare(b.title)