Update README, install instructions, docs mentions, and add createStore deprecation

markerikson · markerikson · commit f90c117dd433 · 2023-11-24T14:45:54.000-05:00
diff --git a/docs/introduction/getting-started.md b/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
 
diff --git a/docs/migrations/1.x-to-2.x.md b/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**. The changes most likely to need app code updates are:
+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**.
+
+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
diff --git a/packages/toolkit/README.md b/packages/toolkit/README.md
@@ -6,24 +6,28 @@
 
 **The official, opinionated, batteries-included toolset for efficient Redux development**
 
-(Formerly known as "Redux Starter Kit")
-
 ## Installation
 
-### Using Create React App
+### Create a React Redux App
 
-The recommended way to start new apps with React and Redux Toolkit is by using the [official Redux+JS template](https://github.com/reduxjs/cra-template-redux) for [Create React App](https://github.com/facebook/create-react-app), which takes advantage of React Redux's integration with React components.
+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).
 
-```sh
-npx create-react-app my-app --template 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.
 
-Or if you are a TypeScript user, use [cra-template-redux-typescript](https://github.com/reduxjs/cra-template-redux-typescript), which is based on that template
+```bash
+# Vite with our Redux+TS template
+# (using the `degit` tool to clone and extract the template)
+npx degit reduxjs/redux-templates/packages/vite-template-redux my-app
 
-```sh
-npx create-react-app my-app --template redux-typescript
+# Next.js using the `with-redux` template
+npx create-next-app --example with-redux my-app
 ```
 
+We do not currently have official React Native templates, but recommend these templates for standard React Native and for Expo:
+
+- https://github.com/rahsheen/react-native-template-redux-typescript
+- https://github.com/rahsheen/expo-template-redux-typescript
+
 ### An Existing App
 
 Redux Toolkit is available as a package on NPM for use with a module bundler or in a Node application:
@@ -36,8 +40,13 @@ npm install @reduxjs/toolkit
 yarn add @reduxjs/toolkit
 ```
 
-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.
+
+## Documentation
+
+The Redux Toolkit docs are available at **https://redux-toolkit.js.org**, including API references and usage guides for all of the APIs included in Redux Toolkit.
+
+The Redux core docs at https://redux.js.org includes the full Redux tutorials, as well usage guides on general Redux patterns.
 
 ## Purpose
 
@@ -67,6 +76,8 @@ Redux Toolkit includes these APIs:
 - `createEntityAdapter()`: generates a set of reusable reducers and selectors to manage normalized data in the store
 - The `createSelector()` utility from the [Reselect](https://github.com/reduxjs/reselect) library, re-exported for ease of use.
 
+For details, see [the Redux Toolkit API Reference section in the docs](https://redux-toolkit.js.org/api/configureStore).
+
 ## RTK Query
 
 **RTK Query** is provided as an optional addon within the `@reduxjs/toolkit` package. It is purpose-built to solve the use case of data fetching and caching, supplying a compact, but powerful toolset to define an API interface layer for your app. It is intended to simplify common cases for loading data in a web application, eliminating the need to hand-write data fetching & caching logic yourself.
@@ -93,7 +104,3 @@ RTK Query includes these APIs:
 - `setupListeners()`: A utility used to enable refetchOnMount and refetchOnReconnect behaviors.
 
 See the [**RTK Query Overview**](https://redux-toolkit.js.org/rtk-query/overview) page for more details on what RTK Query is, what problems it solves, and how to use it.
-
-## Documentation
-
-The Redux Toolkit docs are available at **https://redux-toolkit.js.org**.
