Edits and reshuffling of content for the "Migrations" page

Author: markerikson

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

@@ -1,7 +1,7 @@
 ---
-id: 1.x-to-2.x
-title: 1.x → 2.x
-sidebar_label: 1.x → 2.x
+id: migrating-1.x-to-2.x
+title: Migrating 1.x → 2.x
+sidebar_label: Migrating 1.x → 2.x
 hide_title: true
 toc_max_heading_level: 4
 ---
@@ -10,33 +10,31 @@ toc_max_heading_level: 4
 
 <div className="migration-guide">
 
-# 1.x → 2.x
+# Migrating 1.x → 2.x
 
 ## Introduction
 
-<!-- TODO: some blurb here about how cool 2.0 is -->
+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.
 
-## Breaking Changes
-
-### Core, Toolkit and React Redux
-
-#### Action types _must_ be strings
+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.
 
-We've always specifically told our users that [actions and state _must_ be serializable](https://redux.js.org/style-guide/#do-not-put-non-serializable-values-in-state-or-actions), and that `action.type` _should_ be a string. This is both to ensure that actions are serializable, and to help provide a readable action history in the Redux DevTools.
+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.
 
-`store.dispatch(action)` now specifically enforces that `action.type` _must_ be a string and will throw an error if not, in the same way it throws an error if the action is not a plain object.
+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:
 
-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.
+- [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)
+- [`Middleware` type changed - Middleware `action` and `next` are typed as `unknown`](#middleware-type-changed---middleware-action-and-next-are-typed-as-unknown)
 
-#### Dropping UMD builds
+## Packaging Changes (all)
 
-Redux has always shipped with UMD build artifacts. These are primarily meant for direct import as script tags, such as in a CodePen or a no-bundler build environment.
+We've made updates to the build packaging for all of the Redux-related libraries. These are technically "breaking", but _should_ be transparent to end users, and actually enable better support for scenarios such as using Redux via ESM files under Node.
 
-For now, we're dropping those build artifacts from the published package, on the grounds that the use cases seem pretty rare today.
+#### Addition of `exports` field in `package.json`
 
-We do have a browser-ready ESM build artifact included at dist/redux.browser.mjs, which can be loaded via a script tag that points to that file on Unpkg.
+We've migrated the package definitions to include the `exports` field for defining which artifacts to load, with a modern ESM build as the primary artifact (with CJS still included for compatibility purposes).
 
-If you have strong use cases for us continuing to include UMD build artifacts, please let us know!
+We've done local testing of the package, but we ask the community to try out this in your own projects and report any breakages you find!
 
 #### Build Artifact Modernization
 
@@ -46,23 +44,27 @@ We've updated the build output in several ways:
 - Moved all build artifacts to live under ./dist/, instead of separate top-level folders
 - The lowest Typescript version we test against is now 4.7
 
-#### Addition of `exports` field in `package.json`
+#### Dropping UMD builds
+
+Redux has always shipped with UMD build artifacts. These are primarily meant for direct import as script tags, such as in a CodePen or a no-bundler build environment.
 
-We've migrated the package definitions to be a full `{type: "module"}` ESM package with an `exports` field (with CJS still included for compatibility purposes).
+For now, we're dropping those build artifacts from the published package, on the grounds that the use cases seem pretty rare today.
 
-We've done local testing of the package, but we ask the community to try out this in your own projects and report any breakages you find!
+We do have a browser-ready ESM build artifact included at `dist/$PACKAGE_NAME.browser.mjs`, which can be loaded via a script tag that points to that file on Unpkg.
 
-#### Error message extraction
+If you have strong use cases for us continuing to include UMD build artifacts, please let us know!
 
-Redux 4.1.0 optimized its bundle size by [extracting error message strings out of production builds](https://github.com/reduxjs/redux/releases/tag/v4.1.0), based on React's approach. We've applied the same technique to RTK. This saves about 1000 bytes from prod bundles (actual benefits will depend on which imports are being used).
+## Breaking Changes
+
+### Core
 
-#### Internal listener implementation
+#### Action types _must_ be strings
 
-The Redux store has always used an array to track listener callbacks, and used `listeners.findIndex` to remove listeners on unsubscribe. As we found in React Redux, that can have perf issues when many listeners are unsubscribing at once.
+We've always specifically told our users that [actions and state _must_ be serializable](https://redux.js.org/style-guide/#do-not-put-non-serializable-values-in-state-or-actions), and that `action.type` _should_ be a string. This is both to ensure that actions are serializable, and to help provide a readable action history in the Redux DevTools.
 
-In React Redux, we fixed that with a more sophisticated linked list approach. Here, we've updated the listeners to be stored in a `Map` instead, which has better delete performance than an array.
+`store.dispatch(action)` now specifically enforces that `action.type` _must_ be a string and will throw an error if not, in the same way it throws an error if the action is not a plain object.
 
-In practice this shouldn't have any real effect, because React Redux sets up a subscription in `<Provider>`, and all nested components subscribe to that. But, nice to fix it here as well.
+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.
 
 <div class="typescript-only">
 
@@ -72,7 +74,7 @@ In 2019, we began a community-powered conversion of the Redux codebase to TypeSc
 
 However, the TS-converted code in master has sat around since then, unused and unpublished, due to concerns about possible compatibility issues with the existing ecosystem (as well as general inertia on our part).
 
-Redux core v5 is now built from that converted source code. In theory, this should be almost identical in both runtime behavior and types to the 4.x build, but it's very likely that some of the changes may cause types issues.
+Redux core v5 is now built from that TS-converted source code. In theory, this should be almost identical in both runtime behavior and types to the 4.x build, but it's very likely that some of the changes may cause types issues.
 
 Please report any unexpected compatibility issues on [Github](https://github.com/reduxjs/redux/issues)!
 
@@ -305,6 +307,10 @@ const customCreateApi = buildCreateApi(
 )
 ```
 
+#### Error message extraction
+
+Redux 4.1.0 optimized its bundle size by [extracting error message strings out of production builds](https://github.com/reduxjs/redux/releases/tag/v4.1.0), based on React's approach. We've applied the same technique to RTK. This saves about 1000 bytes from prod bundles (actual benefits will depend on which imports are being used).
+
 <div class="typescript-only">
 
 #### Non-default middleware/enhancers must use `Tuple`
@@ -338,9 +344,9 @@ If you prefer to assume that the lookups _might_ be undefined, use TypeScript's
 
 </div>
 
-## Features
+## New Features
 
-<!-- TODO: some blurb here about how new features are only in toolkit(?) -->
+These features are new in Redux Toolkit 2.0, and help cover additional use cases that we've seen users ask for in the ecosystem.
 
 ### `combineSlices` API with slice reducer injection for code-splitting
 
@@ -445,7 +451,7 @@ expect(selectSlice(customState)).toBe(slice.getInitialState())
 expect(selectMultiple(customState, 2)).toBe(slice.getInitialState() * 2)
 ```
 
-### Callback syntax for `createSlice.reducers`
+### `createSlice.reducers` callback syntax and thunk support
 
 One of the oldest feature requests we've had is the ability to declare thunks directly inside of `createSlice`. Until now, you've always had to declare them separately, give the thunk a string action prefix, and handle the actions via `createSlice.extraReducers`:
 
@@ -484,9 +490,9 @@ We've _wanted_ to include a way to define thunks directly inside of `createSlice
 
 We've settled on these compromises:
 
+- **In order to create async thunks with `createSlice`, you specifically need to [set up a custom version of `createSlice` that has access to `createAsyncThunk`](../api/createSlice#createasyncthunk)**.
 - You can declare thunks inside of `createSlice.reducers`, by using a "creator callback" syntax for the `reducers` field that is similar to the `build` callback syntax in RTK Query's `createApi` (using typed functions to create fields in an object). Doing this does look a bit different than the existing "object" syntax for the `reducers` field, but is still fairly similar.
 - You can customize _some_ of the types for thunks inside of `createSlice`, but you _cannot_ customize the `state` or `dispatch` types. If those are needed, you can manually do an `as` cast, like `getState() as RootState`.
-- In order to create async thunks with `createSlice`, you specifically need to [set up a version that uses `createAsyncThunk`](../api/createSlice#createasyncthunk).
 
 In practice, we hope these are reasonable tradeoffs. Creating thunks inside of `createSlice` has been widely asked for, so we think it's an API that will see usage. If the TS customization options are a limitation, you can still declare thunks outside of `createSlice` as always, and most async thunks don't need `dispatch` or `getState` - they just fetch data and return. And finally, setting up a custom `createSlice` allows you to opt into `createAsyncThunk` being included in your bundle size (though it may already be included if used directly or as part of RTK Query - in either of these cases there's no _additional_ bundle size).
 
@@ -554,7 +560,7 @@ export const { addTodo, deleteTodo, fetchTodo } = todosSlice.actions
 
 #### Codemod
 
-Using the new callback syntax is entirely optional (the object syntax is still standard), but an existing slice would need to be converted before it can take advantage of the new capabilities this syntax provides. To make this easier, a [codemod](../api/codemods) is provided.
+**Using the new callback syntax is entirely optional (the object syntax is still standard)**, but an existing slice would need to be converted before it can take advantage of the new capabilities this syntax provides. To make this easier, a [codemod](../api/codemods) is provided.
 
 ```sh
 npx @reduxjs/rtk-codemods createSliceReducerBuilder ./src/features/todos/slice.ts
@@ -593,7 +599,7 @@ We've updated `configureStore` to add the `autoBatchEnhancer` to the store setup
 
 [`entityAdapter.getSelectors()`](../api/createEntityAdapter#selector-functions) now accepts an options object as its second argument. This allows you to pass in your own preferred `createSelector` method, which will be used to memoize the generated selectors. This could be useful if you want to use one of Reselect's new alternate memoizers, or some other memoization library with an equivalent signature.
 
-### New dev checks in `reselect` v5
+### New dev checks in Reselect v5
 
 Reselect v5 includes a dev-only check to check stability of input selectors, by running them an extra time with the same parameters, and checking that the result matches.
 
@@ -791,7 +797,7 @@ const todoSlice = createSlice({
 export const { selectTodosByAuthor } = todoSlice.selectors
 ```
 
-With `reselect`'s default cache size of 1, this can cause caching issues if called in multiple components with different arguments. One typical solution for this (without `createSlice`) is a [selector factory](https://redux.js.org/usage/deriving-data-selectors#creating-unique-selector-instances):
+With `createSelector`'s default cache size of 1, this can cause caching issues if called in multiple components with different arguments. One typical solution for this (without `createSlice`) is a [selector factory](https://redux.js.org/usage/deriving-data-selectors#creating-unique-selector-instances):
 
 ```ts
 export const makeSelectTodosByAuthor = () =>

website/sidebars.json

@@ -6,11 +6,7 @@
       "collapsed": false,
       "items": ["introduction/getting-started"]
     },
-    {
-      "type": "category",
-      "label": "Migrations",
-      "items": ["migrations/1.x-to-2.x"]
-    },
+
     {
       "type": "category",
       "label": "Tutorials",
@@ -27,6 +23,11 @@
       "label": "Using Redux Toolkit",
       "collapsed": false,
       "items": [
+        {
+          "type": "category",
+          "label": "Migrations",
+          "items": ["migrations/migrating-1.x-to-2.x"]
+        },
         "usage/usage-guide",
         "usage/usage-with-typescript",
         "usage/immer-reducers"