@reduxjs/toolkit releases

2.13.0

29 Sep 2026

Additional publishing hardening
codegen: Migrate to oazapfts v7
combineSlices: Scope stateProxyMap per instance to prevent cross-instance proxy collisions

This feature release updates our build tooling to TSDown and PNPM, adds official TypeScript 7 support, and includes a long list of bugfixes across RTK Query, createAsyncThunk, createEntityAdapter, and combineSlices.

Changelog

Build Tooling Updates

We've fully modernizing modernized our build tooling across all of the Redux repos. That included switching from Yarn to PNPM, ESLint to Oxlint, Prettier to Oxfmt, and TSUp to TSDown.

The part that matters for users is that we now build the package with TSDown instead of tsup. The package layout, exports definitions, and exported APIs are all unchanged from 2.12. We've checked the new build with attw, and verified that CJS and ESM entry points load in both dev and prod builds, and that the legacy-esm artifacts still target ES2017. The contents of the bundles do look a bit different (smaller CJS artifacts, slightly different helper output in the legacy-esm files). If you see any behavior differences that look build-related, please file an issue!

This is also our first release published via the updated PNPM-based workflow, still using NPM Trusted Publishing. We've also added pkg.pr.new previews for every commit, so you can try out a PR build before it's released.

Docs Updates

We've shipped a new combined Redux libraries docs site! The core docs site at redux.js.org now contains the docs for all of our libraries: Redux core and usage guides, Redux Toolkit, React Redux, and Reselect. The prior standalone docs sites for RTK, R-R, and Reselect now redirect to their respective sections of the combined docs. We've also done a major cleanup pass on the docs, deduplicating pages that had similarities (like the Next.js or RTK2 migration pages that lived in both the core and RTK docs), and updating outdated content (modernizing example code snippets, deleting dead links, and making RTK and hooks the default patterns shown). The RTK content now lives at redux.js.org/toolkit/ .

TypeScript 7 Support

TS 7.0 (the native Go port) is now out! We fixed the remaining type errors in RTK when checked by TS 7.0 and 7.1, and TS 7.0 is now part of our CI test matrix.

Per our TS support policy of matching DefinitelyTyped's support window, we've also updated our support matrix to TS 5.6+. As always, RTK may still work with earlier versions, but we no longer test against them.

RTK Query Fixes

useQueryState (and thus useQuery) was passing a new inline selector to useSelector on every render, and also reading the store directly during render. The selector is now memoized, and the direct store read is gone. This also fixes a bug where isSuccess could flip from false to true on an unrelated re-render while a query was refetching after an error. isSuccess now correctly stays false in that case.

data now reflects cache updates made via updateQueryData while a refetch is in flight, instead of showing the previous result.

Polling now reads the current cache state when each poll fires, rather than the state at the time the poll was scheduled. This means skipPollingIfUnfocused respects focus loss that happens after scheduling, and polls stop if their cache entry was removed.

We fixed a race where a duplicate query request rejected by the thunk condition could cause queued tag invalidations to run too early and be lost, leaving stale data in the cache.

Tags with falsy ids like 0 now invalidate and clean up correctly.

Lazy query hooks now re-subscribe correctly when effects restart while the hook state is preserved, such as with Fast Refresh or <Activity>.

Infinite queries no longer trigger onQueryStarted when fetching past the end of the list, and the infinite query hook result type now includes the page error flags.

fetchBaseQuery only treats a URL as absolute if it starts with a scheme.

We also fixed an error when rehydrating state for an endpoint name that has no definition.

Other Fixes

createAsyncThunk no longer swallows aborts that happen before the pending action is dispatched, and now correctly sets rejectedWithValue when rejectWithValue is called with a falsy payload.

createEntityAdapter's setAll now keeps the last item when given duplicate IDs, matching setMany. The sorted adapter's updateMany now merges multiple updates for the same ID before applying them.

combineSlices now keeps its internal state proxy cache per instance, so multiple combined reducers no longer interfere with each other.

The immutability check middleware now handles circular references in state.

The dynamic middleware now caches its composed middleware chains when the list of middleware hasn't changed.

What's Changed

Additional publishing hardening
codegen: Migrate to oazapfts v7
combineSlices: Scope stateProxyMap per instance to prevent cross-instance proxy collisions
entityAdapter: pre-merge same-ID updates in sorted adapter's updateMany
entityAdapter: setAll with duplicate IDs keeps last occurrence (consistent with setMany)
query: Reflect cache updates in hook data
Don't swallow createAsyncThunk aborts that happen before pending
Simplify useRef<T | undefined>(undefined) usages in RTK Query hooks
query: Prevent onQueryStarted from triggering at end-of-list
types: Fix tsgo (TS 7.0) type errors and re-enable the native-preview CI job
Modernize CI examples
rtk-query: Only treat a url as absolute when it starts with a scheme
Modern Tooling, Part 1: Oxlint
Modern Tooling, Part 2: Oxfmt
Modern Tooling, Part 3: TSDown and TS6
Modern Tooling, Part 4: Vitest type assertions
Modern Tooling, Part 5: PNPM
Modern Tooling, Part 6: TS7
Modern Tooling, Part 7: vendor remark-typescript-tools and update to TS7
Modern Tooling, Part 8: Vitest 5
Remove redundant RTK Query example projects
Type the reducer builder implementation explicitly for TS 7.1
toolkit: Flag rejectedWithValue for falsy rejectWithValue payloads
Cache unchanged dynamic middleware chains
Preserve delayed invalidations after duplicate query rejection
Read current query state when scheduled polls fire
toolkit: Prevent undefined endpoint reference
toolkit: Tag with a falsy id invalidation and cleanup
rtk-query: Add infinite query page error flags to hook result type
Reinstate lazy queries after preserved effects restart
toolkit: Handle circular references in immutableStateInvariantMiddleware
Fix TS7 errors and update TS matrix
Fix unstable selector reference inside of useQueryState and isSuccess during refetch-after-error

2.12.0

15 May 2026

breaking
toolkit: Switch to native NoInfer utility type
Export hook options types for RTK Query hooks
Add TanStack Intent skills for Redux Toolkit

2.11.2

14 Dec 2025

Use a normal Error when DOMException isn't available
Include page functions in TypedUseInfiniteQueryHookResult

2.11.1

8 Dec 2025

Use trusted publishing and harden workflows
Update TS typecheck matrix and add TS native job
Officially document TS support

This bugfix release fixes an issue with our internal AbortSignal handling that was reported as causing an error in a rare reset situation. We've also restructured our publishing process to use NPM Trusted Publishing, and updated our TS support matrix to only support TS 5.4+.

Changelog

Publishing Changes

We've previously done most of our releases semi-manually locally, with various release process CLI tools. With the changes to NPM publishing security and the recent wave of NPM attacks, we've updated our publishing process to solely use NPM Trusted Publishing via workflows. We've also done a hardening pass on our own CI setup.

We had done a couple releases via CI workflows previously, and later semi-manual releases caused PNPM to warn that RTK was no longer trusted. This release should be trusted and will resolve that issue.

Thanks to the e18e folks and their excellent guide at e18e.dev/docs/publishing for making this process easier!

TS Support Matrix Updates

We've previously mentioned rolling changes to our TS support matrix in release notes, but didn't officially document our support policy. We've added a description of the support policy (last 2 years of TS releases, matching DefinitelyTyped) and the current oldest TS version we support in the docs:

As of today, we've updated the support matrix to be TS 5.4+ . As always, it's possible RTK will work if you're using an earlier version of TS, but we don't test against earlier versions and don't support any issues with those versions.

We have run an initial test with the upcoming TS 7.0 native tsgo release. We found a couple minor issues with our own TS build and test setup, but no obvious issues with using RTK with TS 7.0.

Bug Fixes

A user reported a rare edge case where the combination of resetApiState and retry() could lead to an error calling an AbortController. We've restructured our AbortController handling logic to avoid that (and simplified a bit of our internals in the process).

What's Changed

Use trusted publishing and harden workflows
Update TS typecheck matrix and add TS native job
Officially document TS support
Tweaks to AbortSignal logic

2.11.0

23 Nov 2025

Update Immer to v11 for better update performance
Compare paths against Regex instances in ignoredPaths
Add refetchCachedPages option for infinite query

This feature release upgrades our Immer dependency to v11 to pick up the additional recent performance optimizations, adds a new refetchCachedPages option to allow only fetching the first cached page, and fixes an issue with regex ignore paths in the immutability middleware.

Changelog

Immer v11 Performance Improvements

As described in the release notes for v2.10.0, we recently put significant effort into profiling Immer, and contributed several PRs that aimed to optimize its update performance.

v2.10.0 updated to use Immer 10.2.0, which added the first smaller set of perf updates. That included a new Immer option to disable "strict iteration" to speed up iterating copied objects, and we specifically applied that change in RTK under the assumption that standard plain JS objects as Redux state shouldn't have unusual keys anyway. Overall, this appears to boost Immer update perf by ~+20% over v10.1 depending on update scenario.

Immer v11.0.0 was just released and contains the second perf PR, a major internal architectural rewrite to change the update finalization implementation from a recursive tree traversal to a set of targeted updates based on accessed and updated fields. Based on the benchmarks in the PR, this adds another ~+5% perf boost over the improvements in v10.2, again with variations depending on update scenario. In practice, the actual improvement may be better than that - the benchmarks list includes some array update cases which actually got a bit slower (and thus drag down the overall average), and a majority of update scenarios show anywhere from +25% to +60% faster than Immer v10.1!

As a practical example, we have an RTK Query stress test benchmark where we mount 1000 components with query hooks at once, unmount, then remount them. We ran the same benchmark steps for RTK 2.9 and Immer 10.1, and then RTK 2.10+ and Immer 11. The overall scripting time dropped by about 30% (3330ms -> 2350ms), and the amount of time spent in Immer methods and the RTK reducers dropped significantly:

Based on this, it appears to be a major improvement overall.

As with the instructions in v2.10.0: if by some chance your Redux app state relies on non-string keys, you can still manually call setUseStrictIteration(true) in your app code to retain compatibility there, but we don't expect that standard Redux apps will have to worry about that.

There are still two outstanding Immer perf PRs that may offer further improvements: one that adds an optional plugin to override array methods to avoid proxy creation overhead, and another experimental tweak to shallow copying that may be better with larger object sizes.

New refetchCachedPages Option

RTK Query's infinite query API was directly based on React Query's approach, including the pages cache structure and refetching behavior. By default, that means that when you trigger a refetch, both R-Q and RTKQ will try to sequentially refetch all pages currently in that cache entry. So, if there were 5 pages cached for an entry, they will try to fetch pages 0...4, in turn.

Some users have asked for the ability to only refetch the first page. This can be accomplished somewhat manually by directly updating the cache entry to eliminate the old pages and then triggering a refetch, but that's admittedly not very ergonomic.

We've merged a contributed PR that adds a new refetchCachedPages flag. This can be defined as part of infinite query endpoints, passed as an option to infinite query hooks, or passed as an option in initiate() calls or hook refetch() methods. If set to refetchCachedPages: false, it will only refetch the first page in the cache and not the remaining pages, thus shrinking the cache from N pages to 1 page.

Other Fixes

We merged a fix to the immutability dev middleware where it was treating ignoredPath regexes as strings and not actually testing them correctly.

What's Changed

Update Immer to v11 for better update performance
Compare paths against Regex instances in ignoredPaths
Add refetchCachedPages option for infinite query

2.10.1

4 Nov 2025

Fix window SSR breakage

2.10.0

4 Nov 2025

Improve perf for internal map/filter ops
Update Immer dep to 10.2 and disable strict iteration for perf
Deduplicate imports

This feature release updates our Immer dep to 10.2 to pick up its performance improvements, has additional byte-shaving and internal performance updates, and fixes a combineSlices type issue.

Changelog

Immer Performance Improvements

Redux Toolkit has been built around Immer since the very first prototype in 2018. Use of Immer as the default in createSlice directly eliminated accidental mutations as a class of errors in Redux apps, and drastically simplified writing immutable updates in reducers.

We've had various issues filed over the years asking to make Immer optional, or raising concerns about Immer's perf. Immer is indeed slower than writing immutable updates by hand, but our stance has always been that Immer's DX is absolutely worth whatever modest perf cost it might incur, and that reducers are usually not the bottleneck in Redux apps anyway - it's usually the cost of updating the UI that's more expensive.

However, a year ago an issue was filed with some specific complaints about Immer perf being very slow. We investigated, ran benchmarks, and filed an Immer issue confirming that it had gotten noticeably slower over time. Immer author Michel Weststrate agreed, and said there were some potential tweaks and architectural changes that could be made, but didn't have time to look into them himself.

A couple months ago, we started investigating possible Immer perf improvements ourselves, including profiling various scenarios and comparing implementations of other similar immutable update libraries. After extensive research and development, we were able to file several PRs to improve Immer's perf: a set of smaller tweaks around iteration and caching, a couple much larger architectural changes, and a potential change to copying objects.

Immer 10.2.0 contains the first set of smaller perf improvements, and this RTK release updates our dependency to 10.2 to pick up those changes.

One important behavior note here: Earlier versions of Immer (8, 9, 10.1) added more handling for edge cases like symbol keys in objects. These changes made sense for correctness, but also contributed to the slowdown. Immer 10.2 now includes a new setUseStrictIteration option to allow only copying string keys in objects (using Object.keys() instead of Reflect.ownKeys()), but keeps the option as strict: true for compatibility with its own users. That default will likely change in Immer 11.

For RTK 2.10.0, we specifically import and call setUseStrictIteration(false), under the assumption that standard Redux state usage only involves string keys in plain JS objects! This should provide a ~10% speedup for Immer update operations. Given that expectation, we believe this is a reasonable feature change and only needs a minor version bump.

If by some chance you are using symbol keys in your Redux state, or in other Immer-powered updates in your Redux app, you can easily revert to the previous behavior by calling setUseStrictIteration(true) in your own app code.

Based on discussions with Michel, Immer v11 should come out in the near future with additional architectural changes for better perf, including optional support for faster array methods that would be available as an Immer plugin adding ~2KB bundle size. We will likely not turn that plugin on by default, but recommend that users enable it if they do frequent array ops in reducers.

We're happy to have contributed these perf improvements to Immer, and that they will benefit not just RTK users but all Immer users everywhere!

You can follow the additional discussion and progress updates in the main Immer perf update tracking issue.

Additional RTK Perf Improvements

We've tweaked some places where we were doing repeated filter().map().map() calls to micro-optimize those loops.

RTKQ tag invalidation was always reading from proxy-wrapped arrays when rewriting provided tags. It now reads from the plain arrays instead, providing a modest speedup.

We previously found that ESBuild wasn't deduplicating imports from the same libraries in separate files bundled together (ie import { useEffect as useEffect2/3/4/ } from 'react'). We've restructured our internals to ensure all external imports are only pulled in once.

We've done some extensive byte-shaving in various places in the codebase. The byte-shaving and import deduplication saves about 0.6K min from the RTKQ core, and 0.2K min from the RTKQ React bundle.

Other Changes

combineSlices now better handles cases where PreloadedState might not match the incoming type, such as persisted values.

What's Changed

Improve perf for internal map/filter ops
Update Immer dep to 10.2 and disable strict iteration for perf
Deduplicate imports
Byte-shave various chunks of code
combineSlices: Infer PreloadedState properly from provided slice

2.9.2

22 Oct 2025

Fix potential subscription leakage in SSR environments
Improve fetchBaseQuery default headers handling
Respect maxRetries for unexpected errors

This bugfix release fixes a potential internal data leak in SSR environments, improves handling of headers in fetchBaseQuery, improves retry handling for unexpected errors and request aborts, and fixes a longstanding issue with prefetch leaving an unused subscription. We've also shipped a new graphqlRequestBaseQuery release with updated dependencies and better error handling.

Changelog

Internal Subscription Handling

We had a report that a Redux SSR app had internal subscription data showing up across different requests. After investigation, this was a bug introduced by the recent RTKQ perf optimizations, where the internal subscription fields were hoisted outside of the middleware setup and into createApi itself. This meant they existed outside of the per-store-instance lifecycle. We've reworked the logic to ensure the data is per-store again. We also fixed another issue that miscalculated when there was an active request while checking for cache entry cleanup.

Note that no actual app data was leaked in this case, just the internal subscription IDs that RTKQ uses in its own middleware to track the existence of subscriptions per cache entry.

fetchBaseQuery Headers

We've updated fetchBaseQuery to avoid setting content-type in cases where a non-JSONifiable value like FormData is being passed as the request body, so that the browser can set that content type itself. It also now sets the accept header based on the selected responseHandler (JSON or text).

retry Behavior and Cleanup

The retry util now respects the maxRetries option when catching unknown errors in addition to the existing known errors logic. It also now checks the request's AbortSignal and will stop retrying if aborted.

In conjunction with that, dispatching resetApiState will now abort all in-flight requests.

The prefetch util and usePrefetch hook had a long-standing issue where they would create a subscription for a cache entry, but there was no way to clean up that subscription. This meant that the cache entry was effectively permanent. They now initiate the request without adding a subscription. This will fetch the cache entry and leave it in the store for the keepUnusedDataFor period as intended, giving your app time to actually subscribe to the value (such as prefetching the cache entry in a route handler, and then subscribing in a component).

graphqlRequestBaseQuery

We've published @rtk-query/graphql-request-base-query v2.3.2, which updates the graphql-request dep to ^7. We also fixed an issue where the error handling rethrew unknown errors - it now returns {error} as a base query is supposed to.

What's Changed

Fix potential subscription leakage in SSR environments
Improve fetchBaseQuery default headers handling
Respect maxRetries for unexpected errors
Update graphql-request dependency to include version ^7.0.0
Add retry abort handling and abort on resetApiState
Don't create subscriptions for prefetch calls

2.9.1

17 Oct 2025

entityAdapter: Ensure sorted addMany keeps first occurrence of duplicate ids
entityAdapter: Ensure sorted setMany keeps just unique IDs in state.ids
types: Ensure non-undefined data on isSuccess with exactOptionalPropertyTypes

2.9.0

3 Sep 2025

Add RawResultType as a type-only property on endpoints
Allow passing an array of specific schemas to skip
types: re-exporting WritableDraft from immer

This feature release rewrites RTK Query's internal subscription and polling systems and the useStableQueryArgs hook for better perf, adds automatic AbortSignal handling to requests still in progress when a cache entry is removed, fixes a bug with the transformResponse option for queries, adds a new builder.addAsyncThunk method, and fixes assorted other issues.

Changelog

RTK Query Performance Improvements

We had reports that RTK Query could get very slow when there were thousands of subscriptions to the same cache entry. After investigation, we found that the internal polling logic was attempting to recalculate the minimum polling time after every new subscription was added. This was highly inefficient, as most subscriptions don't change polling settings, and it required repeated O(n) iteration over the growing list of subscriptions. We've rewritten that logic to debounce the update check and ensure a max of one polling value update per tick for the entire API instance.

Related, while working on the request abort changes, testing showed that use of plain Records to hold subscription data was inefficient because we have to iterate keys to check size. We've rewritten the subscription handling internals to use Maps instead, as well as restructuring some additional checks around in-flight requests.

These two improvements drastically improved runtime perf for the thousands-of-subscriptions-one-cache-entry repro, eliminating RTK methods as visible hotspots in the perf profiles. It likely also improves perf for general usage as well.

We've also changed the implementation of our internal useStableQueryArgs hook to avoid calling serializeQueryArgs on its value, which can avoid potential perf issues when a query takes a very large object as its cache key.

Note

The internal logic switched from serializing the query arg to doing reference checks on nested values. This means that if you are passing a non-POJO value in a query arg, such as useSomeQuery({a: new Set()}), and you have refetchOnMountOrArgChange enabled, this will now trigger refeteches each time as the Set references are now considered different based on equality instead of serialization.

Abort Signal Handling on Cleanup

We've had numerous requests over time for various forms of "abort in-progress requests when the data is no longer needed / params change / component unmounts / some expensive request is taking too long". This is a complex topic with multiple potential use cases, and our standard answer has been that we don't want to abort those requests - after all, cache entries default to staying in memory for 1 minute after the last subscription is removed, so RTKQ's cache can still be updated when the request completes. That also means that it doesn't make sense to abort a request "on unmount".

However, it does then make sense to abort an in-progress request if the cache entry itself is removed. Given that, we've updated our cache handling to automatically call the existing resPromise.abort() method in that case, triggering the AbortSignal attached to the baseQuery. The handling at that point depends on your app - fetchBaseQuery should handle that, a custom baseQuery or queryFn would need to listen to the AbortSignal.

We do have an open issue asking for further discussions of potential abort / cancelation use cases and would appreciate further feedback.

New Options

The builder callback used in createReducer and createSlice.extraReducers now has builder.addAsyncThunk available, which allows handling specific actions from a thunk in the same way that you could define a thunk inside createSlice.reducers:

        const slice = createSlice({
          name: 'counter',
          initialState: {
            loading: false,
            errored: false,
            value: 0,
          },
          reducers: {},
          extraReducers: (builder) =>
            builder.addAsyncThunk(asyncThunk, {
              pending(state) {
                state.loading = true
              },
              fulfilled(state, action) {
                state.value = action.payload
              },
              rejected(state) {
                state.errored = true
              },
              settled(state) {
                state.loading = false
              },
            }),
        })

createApi and individual endpoint definitions now accept a skipSchemaValidation option with an array of schema types to skip, or true to skip validation entirely (in case you want to use a schema for its types, but the actual validation is expensive).

Bug Fixes

The infinite query implementation accidentally changed the query internals to always run transformResponse if provided, including if you were using upsertQueryData(), which then broke. It's been fixed to only run on an actual query request.

The internal changes to the structure of the state.api.provided structure broke our handling of extractRehydrationInfo - we've updated that to handle the changed structure.

The infinite query status fields like hasNextPage are now a looser type of boolean initially, rather than strictly false.

TS Types

We now export Immer's WritableDraft type to fix another non-portable types issue.

We've added an api.endpoints.myEndpoint.types.RawResultType types-only field to match the other available fields.

What's Changed

Add RawResultType as a type-only property on endpoints
Allow passing an array of specific schemas to skip
types: re-exporting WritableDraft from immer
Remove Serialisation from useStableQueryArgs
Add addAsyncThunk method to reducer map builder
Only run transformResponse when a query is used
Assorted bugfixes for 2.8.3
Abort pending requests if the cache entry is removed
Update TS CI config
Rewrite subscription handling and polling calculations for better perf

2.8.2

14 May 2025

Restructure build config to fix RTKQ externals

2.8.1

8 May 2025

browser exports condition

2.8.0

6 May 2025

React-Native package exports
Add queryArg as 5th param to page param functions

2.7.0

16 Apr 2025

The lifecycleApi.updateCachedData method is now correctly available
The skip option now correctly works for infinite query hooks
Infinite query fulfilled actions now include the meta field from the base query (such as {request, response}). For cases where multiple pages are being refetched, this will be the meta from the last page fetched.

RTK has hit Stage 2.7! :rofl: This feature release adds support for Standard Schema validation in RTK Query endpoints, fixes several issues with infinite queries, improves perf when infinite queries provide tags, adds a dev-mode check for duplicate middleware, and improves reference stability in slice selectors and infinite query hooks.

Changelog

Standard Schema Validation for RTK Query

Apps often need to validate responses from the server, both to ensure the data is correct, and to help enforce that the data matches the expected TS types. This is typically done with schema libraries such as Zod, Valibot, and Arktype. Because of the similarities in usage APIs, those libraries and others now support a common API definition called Standard Schema, allowing you to plug your chosen validation library in anywhere Standard Schema is supported.

RTK Query now supports using Standard Schema to validate query args, responses, and errors. If schemas are provided, the validations will be run and errors thrown if the data is invalid. Additionally, providing a schema allows TS inference for that type as well, allowing you to omit generic types from the endpoint.

Schema usage is per-endpoint, and can look like this:

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
import * as v from 'valibot'

const postSchema = v.object({
  id: v.number(),
  name: v.string(),
})
type Post = v.InferOutput<typeof postSchema>

const api = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: '/' }),
  endpoints: (build) => ({
    getPost: build.query({
      // infer arg from here
      query: ({ id }: { id: number }) => `/post/${id}`,
      // infer result from here
      responseSchema: postSchema,
    }),
    getTransformedPost: build.query({
      // infer arg from here
      query: ({ id }: { id: number }) => `/post/${id}`,
      // infer untransformed result from here
      rawResponseSchema: postSchema,
      // infer transformed result from here
      transformResponse: (response) => ({
        ...response,
        published_at: new Date(response.published_at),
      }),
    }),
  }),
})

If desired, you can also configure schema error handling with the catchSchemaFailure option. You can also disable actual runtime validation with skipSchemaValidation (primarily useful for cases when payloads may be large and expensive to validate, but you still want to benefit from the TS type inference).

See the "Schema Validation" docs section in the createApi reference and the usage guide sections on queries, infinite queries, and mutations, for more details.

Infinite Query Fixes

This release fixes several reported issue with infinite queries:

The lifecycleApi.updateCachedData method is now correctly available
The skip option now correctly works for infinite query hooks
Infinite query fulfilled actions now include the meta field from the base query (such as {request, response}). For cases where multiple pages are being refetched, this will be the meta from the last page fetched.
useInfiniteQuerySubscription now returns stable references for refetch and the fetchNext/PreviousPage methods

upsertQueryEntries, Tags Performance and API State Structure

We recently published a fix to actually process per-endpoint providedTags when using upsertQueryEntries. However, this exposed a performance issue - the internal tag handling logic was doing repeated O(n) iterations over all endpoint+tag entries in order to clear out existing references to that cache key. In cases where hundreds or thousands of cache entries were being inserted, this became extremely expensive.

We've restructured the state.api.provided data structure to handle reverse-mapping between tags and cache keys, which drastically improves performance in this case. However, it's worth noting that this is a change to that state structure. This shouldn't affect apps, because the RTKQ state is intended to be treated as a black box and not generally directly accessed by user app code. However, it's possible someone may have depended on that specific state structure when writing a custom selector, in which case this would break. An actual example of this is the Redux DevTools RTKQ panel, which iterates the tags data while displaying cache entries. That did break with this change. Prior to releasing RTK 2.7,we released Redux DevTools 3.2.10, which includes support for both the old and new state.api.provided definitions.

TS Support Matrix Updates

Following with the DefinitelyTyped support matrix, we've officially dropped support for TS 5.0, and currently support TS 5.1 - 5.8. (RTK likely still works with 5.0, but we no longer test against that in CI.)

Duplicate Middleware Dev Checks

configureStore now checks the final middleware array for duplicate middleware references. This will catch cases such as accidentally adding the same RTKQ API middleware twice (such as adding baseApi.middleware and injectedApi.middlweware - these are actually the same object and same middleware).

Unlike the other dev-mode checks, this is part of configureStore itself, not getDefaultMiddleware().

This can be configured via the new duplicateMiddlewareCheck option.

Other Changes

createEntityAdapter now correctly handles adding an item and then applying multiple updates to it.

The generated combineSlices selectors will now return the same placeholder initial state reference for a given slice, rather than returning a new initial state reference every time.

useQuery hooks should now correctly refetch after dispatching resetApiState.

What's Changed

Process multiple update for the same new entity
Add infinite query support for updateCachedData
Add infinite query skip support
Cache initial state in injected scenarios
Rewrite providedTags handling for better perf
Allow standard schemas to validate endpoint values
rtk-query: useQuery hook does not refetch after resetApiState
Drop TS 5.0 from compat matrix
Add duplicate middleware dev check to configureStore
Improve duplicate middleware error and save build output
Add meta handling for infinite queries
Improve stability of useInfiniteQuerySubscription's return value
Add catchSchemaFailure, and docs for RTKQ schema features

2.6.1

7 Mar 2025

matchFulfilled and providesTags now get the correct response types
We've added pre-typed Type* types to represent infinite queries, similar to the existing pre-defined types for queries and mutations
selectCachedArgsForQuery now supports fetching args for infinite query endpoints

2.6.0

23 Feb 2025

RTKQ Infinite Query integration

This feature release adds infinite query support to RTK Query.

Changelog

RTK Query Infinite Query support

Since we first released RTK Query in 2021, we've had users asking us to add support for "infinite queries" - the ability to keep fetching additional pages of data for a given endpoint. It's been by far our most requested feature. Until recently, our answer was that we felt there were too many use cases to support with a single API design approach.

Last year, we revisited this concept and concluded that the best approach was to mimic the flexible infinite query API design from React Query. We had additional discussions with @tkdodo , who described the rationale and implementation approach and encouraged us to use their API design, and @riqts provided an initial implementation on top of RTKQ's existing internals.

We're excited to announce that this release officially adds full infinite query endpoint support to RTK Query!

Using Infinite Queries

As with React Query, the API design is based around "page param" values that act as the query arguments for fetching a specific page for the given cache entry.

Infinite queries are defined with a new build.infiniteQuery() endpoint type. It accepts all of the same options as normal query endpoints, but also needs an additional infiniteQueryOptions field that specifies the infinite query behaviors. With TypeScript, you must supply 3 generic arguments: build.infiniteQuery<ResultType, QueryArg, PageParam>, where ResultType is the contents of a single page, QueryArg is the type passed in as the cache key, and PageParam is the value used to request a specific page.

The endpoint must define an initialPageParam value that will be used as the default (and can be overridden if desired). It also needs a getNextPageParam callback that will calculate the params for each page based on the existing values, and optionally a getPreviousPageParam callback if reverse fetching is needed. Finally, a maxPages option can be provided to limit the entry cache size.

The query and queryFn methods now receive a {queryArg, pageParam} object, instead of just the queryArg.

For the cache entries and hooks, the data field is now an object like {pages: ResultType, pageParams: PageParam>. This gives you flexibility in how you use the data for rendering.

const pokemonApi = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: 'https://example.com/pokemon' }),
  endpoints: (build) => ({
    // 3 TS generics: page contents, query arg, page param
    getInfinitePokemonWithMax: build.infiniteQuery<Pokemon[], string, number>({
      infiniteQueryOptions: {
        // Must provide a default initial page param value
        initialPageParam: 1,
        // Optionally limit the number of cached pages
        maxPages: 3,
        // Must provide a `getNextPageParam` function
        getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) =>
          lastPageParam + 1,
        // Optionally provide a `getPreviousPageParam` function
        getPreviousPageParam: (
          firstPage,
          allPages,
          firstPageParam,
          allPageParams,
        ) => {
          return firstPageParam > 0 ? firstPageParam - 1 : undefined
        },
      },
      // The `query` function receives `{queryArg, pageParam}` as its argument
      query({ queryArg, pageParam }) {
        return `/type/${queryArg}?page=${pageParam}`
      },
    }),
  }),
})

As with all RTKQ functionality, the core logic is UI-agnostic and does not require React. However, using the RTKQ React entry point will also auto-generate useInfiniteQuery hooks for these endpoints. Infinite query hooks fetch the initial page, then provide fetchNext/PreviousPage functions to let you trigger requests for more pages.

function PokemonList({
    pokemonType = 'fire',
  }: {
    pokemonType?: string
   ) {
  const {
    data,
    isFetching,
    isSuccess,
    fetchNextPage,
    fetchPreviousPage,
    refetch,
  } = api.useGetInfinitePokemonInfiniteQuery(pokemonType)

  const handlePreviousPage = async () => {
    const res = await fetchPreviousPage()
  }

  const handleNextPage = async () => {
    const res = await fetchNextPage()
  }
  
  // `data` is a `{pages, pageParams}` object.
  // You can use those to render whatever UI you need.
  // In this case, flatten per-page arrays of results for this endpoint
  // into a single array to render a list.
  const allPokemon = data?.pages.flat() ?? [];

  // render UI with pages, show loading state, fetch as needed
}

Docs and Examples

The RTK Query docs have been updated with new content and explanations for infinite queries:

We've also added a new infinite query example app in the repo that shows several usage patterns like pagination, cursors, infinite scrolling, and limit+offset queries.

Notes

As with all new features and functionality, more code does mean an increase in bundle size.

We did extensive work to byte-shave and optimize the final bundle size for this feature. Final estimates indicate that this adds about 4.2Kmin to production bundles. That's comparable to React Query's infinite query support size.

However, given RTKQ's current architecture, that bundle size increase is included even if you aren't using any infinite query endpoints in your application. Given the significant additional functionality, that seems like an acceptable tradeoff. (And as always, having this kind of functionality built into RTKQ means that your app benefits when it uses this feature without having to add a lot of additional code to your own app, which would likely be much larger.)

Longer-term, we hope to investigate reworking some of RTKQ's internal architecture to potentially make some of the features opt-in for better bundle size optimizations, but don't have a timeline for that work.

What's Changed

- Infinite Query API
RTKQ Infinite Query integration

and numerous specific sub-PRs that went into that integration PR as I worked through the implementation over the last few months.

2.5.1

26 Jan 2025

Ensure upserted cache entries always get written

2.5.0

11 Dec 2024

Migrate to React 19
Handle additional serializeQueryArgs + skipToken case

2.4.0

28 Nov 2024

Add example to reproduce defect of serializeQueryArgs with skipToken
Read window.rAF later to allow fake timers to work correctly
Add type helpers for OnQueryStarted callbacks

This feature release includes multiple tweaks and fixes to RTK Query functionality, additional exported TS types, and drops support for TS versions earlier than 5.0.

Changelog

RTK Query Improvements

Lazy query hooks can now be reset.

retry.fail now accepts meta as a second argument.

Tag invalidation arrays now ignore nullish values.

We did some small internal refactoring around Maps and default values that shrank bundle size slightly.

Bugfixes

Passing skipToken to a query hook now bails out before running any other logic, which fixes cases where serializeQueryArgs previously threw an error because there were no args to process.

The autoBatchEnhancer now reads window.requestAnimationFrame later, which it to work properly with Jest fake timers.

We fixed cases where the hook result isSuccess flag would briefly flicker to false when switched to a different cache entry that was uninitialized, and would briefly flicker to true when refetching a query that previously errored.

The listener middleware previously had inconsistent logic checks for comparing against existing listener entries (effect + type, vs effect only). It now always checks both effect + type.

Additional TS Types

We now export Typed[Query|Mutation]OnQueryStarted helpers to let you define onQueryStarted callbacks outside of createApi if desired.

We also now export a CreateAsyncThunkFunction type that can be used to type userland wrappers around createAsyncThunk.

TS Support Matrix Updates

We've historically tried to maintain TS backwards compatibility as long as possible, and made occasional updates to our TS support matrix in minor versions over time. As of RTK 2.3.0, we officially supported back through TS 4.7.

As of this release, we're tweaking that support policy to match the policy used by DefinitelyTyped:

Definitely Typed only tests packages on versions of TypeScript that are less than 2 years old
image

Given that, we've dropped official support for TS versions earlier than 5.0. (RTK may work with those versions, but we no longer test against them and won't try to fix issues with those versions.)

We'll continue to update our TS support matrix over time based on that 2-year rolling window.

What's Changed

Add example to reproduce defect of serializeQueryArgs with skipToken
Read window.rAF later to allow fake timers to work correctly
Add type helpers for OnQueryStarted callbacks
Add a type for createAsyncThunk without the withTypes method
Add ability to reset lazy query hooks
Ignore nullish values in tag invalidations
Allow passing meta to retry.fail, and passing baseQuery to ensure types match
Keep isSuccess: true when switching to an uninitialized cache entry
Keep isSuccess consistent when refetching after an error
Update to new version of upsert proposal, and fix listener equality checks

2.3.0

14 Oct 2024

arg: the URL string or FetchArgs object that was passed in to fetchBaseQuery for this endpoint
extraOptions: any extra options that were provided to the base query
Fix serializeQueryArgs type

This feature release adds a new RTK Query upsertQueryEntries util to batch-upsert cache entries more efficiently, passes through additional values for use in prepareHeaders, and exports additional TS types around query options and selectors.

Changelog

upsertQueryEntries

RTK Query already had an upsertQueryData thunk that would upsert a single cache entry. However, some users wanted to upsert many cache entries (potentially hundreds or thousands), and found that upsertQueryData had poor performance in those cases. This is because upsertQueryData runs the full async request handling sequence, including dispatching both pending and fulfilled actions, each of which run the main reducer and update store subscribers. That means there's 2N store / UI updates per item, so upserting hundreds of items becomes extremely perf-intensive.

RTK Query now includes an api.util.upsertQueryEntries action that is meant to handle the batched upsert use case more efficiently. It's a single synchronous action that accepts an array of many {endpointName, arg, value} entries to upsert. This results in a single store update, making this vastly better for performance vs many individual upsertQueryData calls.

We see this as having two main use cases. The first is prefilling the cache with data retrieved from storage on app startup (and it's worth noting that upsertQueryEntries can accept entries for many different endpoints as part of the same array).

The second is to act as a "pseudo-normalization" tool. RTK Query is not a "normalized" cache. However, there are times when you may want to prefill other cache entries with the contents of another endpoint, such as taking the results of a getPosts list endpoint response and prefilling the individual getPost(id) endpoint cache entries, so that components that reference an individual item endpoint already have that data available.

Currently, you can implement the "pseudo-normalization" approach by dispatching upsertQueryEntries in an endpoint lifecycle, like this:

const api = createApi({
  endpoints: (build) => ({
    getPosts: build.query<Post[], void>({
      query: () => '/posts',
      async onQueryStarted(_, { dispatch, queryFulfilled }) {
        const res = await queryFulfilled
        const posts = res.data

        // Pre-fill the individual post entries with the results
        // from the list endpoint query
        dispatch(
          api.util.upsertQueryEntries(
            posts.map((post) => ({
              endpointName: 'getPost',
              arg: { id: post.id },
              value: post,
            })),
          ),
        )
      },
    }),
    getPost: build.query<Post, Pick<Post, 'id'>>({
      query: (post) => `post/${post.id}`,
    }),
  }),
})

Down the road we may add a new option to query endpoints that would let you provide the mapping function and have it automatically update the corresponding entries.

For additional comparisons between upsertQueryData and upsertQueryEntries, see the upsertQueryEntries API reference.

prepareHeaders Options

The prepareHeaders callback for fetchBaseQuery now receives two additional values in the api argument:

arg: the URL string or FetchArgs object that was passed in to fetchBaseQuery for this endpoint
extraOptions: any extra options that were provided to the base query

Additional TS Types

We've added a TypedQueryStateSelector type that can be used to pre-type selectors for use with selectFromResult:

const typedSelectFromResult: TypedQueryStateSelector<
  PostsApiResponse,
  QueryArgument,
  BaseQueryFunction,
  SelectedResult
> = (state) => ({ posts: state.data?.posts ?? EMPTY_ARRAY })

function PostsList() {
  const { posts } = useGetPostsQuery(undefined, {
    selectFromResult: typedSelectFromResult,
  })
}

We've also exported several additional TS types around base queries and tag definitions.

What's Changed

Fix serializeQueryArgs type
Add the TypedQueryStateSelector helper type
Pass query args to prepareHeaders function
Implement a util function to batch-upsert cache entries
fetchBaseQuery: Expose extraOptions to prepareHeaders

2.2.8

8 Oct 2024

Export QueryExtraOptions and MutationExtraOptions
Fix mangleErrors not preserving different error types
Add the TypedUseQueryStateOptions helper type

2.2.7

27 Jul 2024

2.2.6

29 Jun 2024

Brings internal useIsomorphicLayoutEffect usage in line with React Redux in React Native environments
Exports FetchBaseQueryArgs type
Fixes an issue in recent createEntityAdapter sorting perf improvements that could (in specific cases) cause Immer to throw an error

2.2.5

16 May 2024

Fix missed spot where use of current may fail if the value is not a draft

2.2.4

9 May 2024

Update remaining Context references to match the new nullable Context
types: Export GetThunkAPI type
Inline the deprecated React.ReactChild type

This bugfix release improves sorting performance in createEntityAdapter, shrinks the code size in matcher utilities, fixes assorted issues with query hooks, and makes several TS tweaks.

Changelog

Entity Adapter Sorting Performance

Users reported in #4252 that the sorting performance of createEntityAdapter seemed abnormally bad - the provided comparison functions were being called far more times than expected.

Upon investigation, we had a couple of problems. We were always starting from an array that was in insertion order, not the existing sorted order, and that would always require significant effort to re-sort even if there weren't any actual changes to the sorted results. Also, the sorting checks required frequent access to Immer's Proxy-wrapped values, even in cases where all we needed was the plain state values for comparison purposes.

We've reworked the internal sorting logic to always start from the existing sorted array, do reads against a plain value to avoid the Proxy getter overhead where possible, and optimized inserts into existing sorted arrays. This should significantly speed up sorted entity adapter behavior.

Matcher Code Size Optimization

We've reworked the internals of the thunk-related matchers to deduplicate some of the logic, shaving a few bytes off the final bundle size.

RTK Query Hook Updates

defaultSerializeQueryArgs can now handle BigInt values safely.

The isLoading flag logic was improved to handle errors when a query hook tries to subscribe.

TS Updates

create.asyncThunk's types were improved to avoid cases where it might infer any.

We've made several internal types changes to work correctly with React 19's upcoming types.

The retryCondition method now receives unknown as an argument, instead of always assuming the user is using fetchBaseQuery.

Other Changes

The Reselect dep has been bumped to 5.1.0 to match the expected internal usage of createSelector.withTypes().

What's Changed

Update remaining Context references to match the new nullable Context
types: Export GetThunkAPI type
Inline the deprecated React.ReactChild type
Replace usage of deprecated JSX global namespace with React.JSX
Fix useRef usages to be called with an explicit argument of undefined.
Bump reselect dependency to 5.1.0 to resolve #4200
Improve sorted entity adapter sorting performance
Prevent inference of any in create.asyncThunk
Try out simplifying matcher code
Handle bigint in useQuerySubscription
Ensure hook subscription failures do not reset isLoading state
Improve usability of the initiate() action for mutations.
Make retryCondition receive unknown error, as the user may not be using fetchBaseQuery

2.2.3

31 Mar 2024

Update React Redux dependency to v9, and update docs to use .withTypes

2.2.2

21 Mar 2024

Rename TypedUseMutationTrigger to TypedMutationTrigger, and add deprecated alias
Fixed memory leak in rapid hook arg changing
Fix incorrect legacy-esm target

2.2.1

14 Feb 2024

2.2.0

12 Feb 2024

Adds a second parameter to entityAdapter.getInitialState(additionalProps, entities) to allow prefilling state
Allows initialising combineSlices with no static reducers
Allows a new 'throw' value for overrideExisting in injectEndpoints, which throws an error if a definition is injected with a name which is already used

This minor release:

Adds a second parameter to entityAdapter.getInitialState(additionalProps, entities) to allow prefilling state
- Equivalent to entityAdapter.setAll(entityAdapter.getInitialState(additionalProps), entities)
- First parameter can be undefined if no additional properties are desired
Allows initialising combineSlices with no static reducers
- Previously const combinedReducer = combineSlices().withLazyLoadedSlices<LazyLoadedSlices>() would have thrown an error
- Now returns a "no-op" reducer that just returns an empty object until first reducer injected
Allows a new 'throw' value for overrideExisting in injectEndpoints, which throws an error if a definition is injected with a name which is already used
Exports more type helpers for RTKQ hook and trigger types
Exports types related to overriding result types in enhanceEndpoints
Fixes state inference for injected slices when undeclared (i.e. not in LazyLoadedSlices)
Adds a action.meta.arg.isPrefetch value to query thunk actions when prefetched

What's Changed

Revamp type tests setup
Bump Prettier and Prettier related packages
Fix codemods to work with TypeScript 4.7+
Export types related to overriding the result types
Migrate type tests to Vitest
Fix RetryOptions type test by flipping order
Format all files
skipPollingIfUnfocused added to polling overview and query options
Temporarily revert node-fetch bump until ESM issues are sorted
Contributing Markdown Refresh
Investigate re-adding size limit action
Add size limit imports for more commonly used RTK exports
Pure some things
Cut back on suffixes tested for size
Incorrect builder method referenced
Rename cli.js to cli.mjs
Fix wrong state for injected slices when not declared via withLazyLoadedSlices
: add missing setOne and setMany signature
Corrected the "Observing cache behaviour" example point no.4
Add isPrefetch property in query action
Allow initialising combined slice reducer with no static slices
Create more Typed wrappers for RTKQ hook types
Proposal fix for axios base query types
Provide 'throw' option for overrideExisting
Use vite-tsconfig-paths to make path aliasing easier
Remove trailing commas in tsconfig.json files of all CodesandBox examples
Add second parameter to getInitialState to prefill entities

2.1.0

24 Jan 2024

Adds withTypes methods to listenerMiddleware and createDraftSafeSelector
Adds a skipPollingIfUnfocused option to RTK Query
Adds the ability to customise the createSelector instance used by RTK Query

This minor release:

Adds withTypes methods to listenerMiddleware and createDraftSafeSelector
Adds a skipPollingIfUnfocused option to RTK Query
Adds the ability to customise the createSelector instance used by RTK Query
Reworks slice selector logic to avoid depending on this value
Fixes the order and inference of create.asyncThunk type parameters
Fixes requirements for meta fields returned from queryFns
Marks promises that will never reject as safe, in preparation for #7008

What's Changed

Update docs to avoid circular type
Copy "Migrating to Modern Redux" and "RTK is Redux" docs from core site
Fix store path rtk-query pokemon api tutorial
Tweak RTKQ without hooks section, and add note regarding memoization
Add section regarding overriding deps
Add section re: RR custom context typing change
Add Expo demo app to CI workflow
Preserve nullable store state type by avoiding intersection with {}
Upgrade version of "graphql-request"
Update RTK peerDependency
Improve selectFromResult memoization
Rename "createSliceWithThunks" and "createThunkSlice" to "createAppSlice"
Bump Vitest to latest version
Fix inference and order of async thunk generics
Fix markdown links on Next.js page
Introduce pre-typed listener middleware via listenerMiddleware.withTypes<RootState, AppDispatch>() method
Add .withTypes to createDraftSafeSelector
Task/remove all settled
Allow customising createSelector instance used by RTKQ
cacheLifecycle fix for fixedCacheKey in mutationThunk
Avoid relying on this in createSlice
documentation: Fix grammar in redux and redux toolkit comparison
Update tsconfig.typetests.json to include all TS files
Remove abort event listner for AbortController
fix/kitchen-sink-isAuthenticated: Fixed isAuthenticated state change on login fullfilled
Fix composeWithDevTools spy
Require queryFn meta to match base query
Added 'SafePromise' branded Promises for createAsyncThunk
Add React Native demo app to CI workflow
Add missing reducer field to ConfigureStoreOptions docs
Option for queries to pause polling when unfocused

2.0.1

4 Dec 2023

2.0.0

4 Dec 2023

removed
Removes the deprecated object syntax from createSlice and createReducer
removed
Removes other deprecated options
removed
Remove remaining deprecated exports

This major release :

removed
Removes the deprecated object syntax from createSlice and createReducer
removed
Removes other deprecated options
Updates the middleware and enhancers options of configureStore to require callbacks
Updates the packaging for better ESM/CJS compatibility and modernizes the build output
Includes all changes to Redux core 5.0, Reselect 5.0, and Redux Thunk 3.0
Updates RTKQ default subscription behavior
Adds a new combineSlices method with support for lazy-loading slice reducers
Adds a new "dynamic middleware" middleware with support for adding middleware at runtime
Adds a new callback syntax to createSlice.reducers, with optional support for defining thunks inside of createSlice
Adds the autoBatchEnhancer to configureStore by default
Has many additional TS tweaks and improvements

This release has breaking changes. (Note: v2.0.1 was released with a couple hotfixes for Reselect and Redux Thunk right as this was being finalized.)

This release is part of a wave of major versions of all the Redux packages: Redux Toolkit 2.0, Redux core 5.0, React-Redux 9.0, Reselect 5.0, and Redux Thunk 3.0.

For full details on all of the breaking changes and other significant changes to all of those packages, see the "Migrating to RTK 2.0 and Redux 5.0" migration guide in the Redux docs.

Note

The Redux core, Reselect, and Redux Thunk packages are included as part of Redux Toolkit, and RTK users do not need to manually upgrade them - you'll get them as part of the upgrade to RTK 2.0. (If you're not using Redux Toolkit yet, please start migrating your existing legacy Redux code to use Redux Toolkit today!)

# RTK
npm install @reduxjs/toolkit
yarn add @reduxjs/toolkit

Changelog

Object syntax for createSlice.extraReducers and createReducer removed

RTK's createReducer API was originally designed to accept a lookup table of action type strings to case reducers, like { "ADD_TODO": (state, action) => {} }. We later added the "builder callback" form to allow more flexibility in adding "matchers" and a default handler, and did the same for createSlice.extraReducers.

We have removed the "object" form for both createReducer and createSlice.extraReducers in RTK 2.0, as the builder callback form is effectively the same number of lines of code, and works much better with TypeScript.

As an example, this:

const todoAdded = createAction('todos/todoAdded')

createReducer(initialState, {
  [todoAdded]: (state, action) => {},
})

createSlice({
  name,
  initialState,
  reducers: {
    /* case reducers here */
  },
  extraReducers: {
    [todoAdded]: (state, action) => {},
  },
})

should be migrated to:

createReducer(initialState, (builder) => {
  builder.addCase(todoAdded, (state, action) => {})
})

createSlice({
  name,
  initialState,
  reducers: {
    /* case reducers here */
  },
  extraReducers: (builder) => {
    builder.addCase(todoAdded, (state, action) => {})
  },
})

Codemods

To simplify upgrading codebases, we've published a set of codemods that will automatically transform the deprecated "object" syntax into the equivalent "builder" syntax.

The codemods package is available on NPM as @reduxjs/rtk-codemods. More details are available here.

To run the codemods against your codebase, run npx @reduxjs/rtk-codemods <TRANSFORM NAME> path/of/files/ or/some**/*glob.js.

Examples:

npx @reduxjs/rtk-codemods createReducerBuilder ./src

npx @reduxjs/rtk-codemods createSliceBuilder ./packages/my-app/**/*.ts

We also recommend re-running Prettier on the codebase before committing the changes.

These codemods should work, but we would greatly appreciate feedback from more real-world codebases!

configureStore Options Changes

configureStore.middleware must be a callback

Since the beginning, configureStore has accepted a direct array value as the middleware option. However, providing an array directly prevents configureStore from calling getDefaultMiddleware(). So, middleware: [myMiddleware] means there is no thunk middleware added (or any of the dev-mode checks).

This is a footgun, and we've had numerous users accidentally do this and cause their apps to fail because the default middleware never got configured.

As a result, we've now made the middleware only accept the callback form. If for some reason you still want to replace all of the built-in middleware, do so by returning an array from the callback:

const store = configureStore({
  reducer,
  middleware: (getDefaultMiddleware) => {
    // WARNING: this means that _none_ of the default middleware are added!
    return [myMiddleware]
    // or for TS users, use:
    // return new Tuple(myMiddleware)
  },
})

But note that we consistently recommend not replacing the default middleware entirely, and that you should use return getDefaultMiddleware().concat(myMiddleware).

configureStore.enhancers must be a callback

Similarly to configureStore.middleware, the enhancers field must also be a callback, for the same reasons.

The callback will receive a getDefaultEnhancers function that can be used to customise the batching enhancer that's now included by default.

For example:

const store = configureStore({
  reducer,
  enhancers: (getDefaultEnhancers) => {
    return getDefaultEnhancers({
      autoBatch: { type: 'tick' },
    }).concat(myEnhancer)
  },
})

It's important to note that the result of getDefaultEnhancers will also contain the middleware enhancer created with any configured/default middleware. To help prevent mistakes, configureStore will log an error to console if middleware was provided and the middleware enhancer wasn't included in the callback result.

const store = configureStore({
  reducer,
  enhancers: (getDefaultEnhancers) => {
    return [myEnhancer] // we've lost the  middleware here
    // instead:
    return getDefaultEnhancers().concat(myEnhancer)
  },
})

Also, note that if you supply the enhancers field, it must come after the middleware field in order for TS inference to work properly.

Standalone getDefaultMiddleware and getType removed

The standalone version of getDefaultMiddleware has been deprecated since v1.6.1, and has now been removed. Use the function passed to the middleware callback instead, which has the correct types.

We have also removed the getType export, which was used to extract a type string from action creators made with createAction. Instead, use the static property actionCreator.type.

RTK Query behaviour changes

We've had a number of reports where RTK Query had issues around usage of dispatch(endpoint.initiate(arg, {subscription: false})). There were also reports that multiple triggered lazy queries were resolving the promises at the wrong time. Both of these had the same underlying issue, which was that RTKQ wasn't tracking cache entries in these cases (intentionally). We've reworked the logic to always track cache entries (and remove them as needed), which should resolve those behavior issues.

We also have had issues raised about trying to run multiple mutations in a row and how tag invalidation behaves. RTKQ now has internal logic to delay tag invalidation briefly, to allow multiple invalidations to get handled together. This is controlled by a new invalidationBehavior: 'immediate' | 'delayed' flag on createApi. The new default behavior is 'delayed'. Set it to 'immediate' to revert to the behavior in RTK 1.9.

In RTK 1.9, we reworked RTK Query's internals to keep most of the subscription status inside the RTKQ middleware. The values are still synced to the Redux store state, but this is primarily for display by the Redux DevTools "RTK Query" panel. Related to the cache entry changes above, we've optimized how often those values get synced to the Redux state for perf.

ESM/CJS Package Compatibility

The biggest theme of the Redux v5 and RTK 2.0 releases is trying to get "true" ESM package publishing compatibility in place, while still supporting CJS in the published package.

The primary build artifact is now an ESM file, dist/redux-toolkit.modern.mjs. Most build tools should pick this up. There's also a CJS artifact, and a second copy of the ESM file named redux-toolkit.legacy-esm.js to support Webpack 4 (which does not recognize the exports field in package.json). Additionally, all of the build artifacts now live under ./dist/ in the published package.

Modernized Build Output

We now publish modern JS syntax targeting ES2020, including optional chaining, object spread, and other modern syntax. If you need to target older browsers, please transpile the packages yourself (or use the legacy-esm build artifact for ES2017).

Build Tooling

We're now building the package using github.com/egoist/tsup. We also now include sourcemaps for the ESM and CJS artifacts.

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 dropped those build artifacts from the published package, on the grounds that the use cases seem pretty rare today.

There's now a redux-toolkit.browser.mjs file in the package that can be loaded from a CDN like Unpkg.

If you have strong use cases for us continuing to include UMD build artifacts, please let us know!

Dependency Updates

Redux Libraries

RTK now depends on Redux core 5.0, Reselect 5.0, and Redux Thunk 3.0. See the linked release notes for those libraries, as each of them has additional breaking changes. The "Migrating to RTK 2.0 and Redux 5.0" docs page also covers the combined changes in one page

Immer 10

RTK now also depends on Immer 10.0, which has several major improvements and updates:

We've also removed the prior call to automatically enable the Immer ES5 fallback mode any time RTK was loaded.

Other Changes

Bundle Size Optimizations

Redux 4.1.0 optimized its bundle size by extracting error message strings out of production builds, 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).

We also noted that ESBuild does not deduplicate imports when it bundles source files, and this was causing RTK Query's bundle to contain a dozen references to import { } from "@reduxjs/toolkit", including some of the same methods. Manually deduplicating those saves about 600 bytes off the production RTKQ artifact.

reactHooksModule custom hook configuration

Previously, custom versions of React Redux's hooks (useSelector, useDispatch, and useStore) could be passed separately to reactHooksModule, usually to enable using a different context to the default ReactReduxContext.

In practicality, the react hooks module needs all three of these hooks to be provided, and it became an easy mistake to only pass useSelector and useDispatch, without useStore.

The module has now moved all three of these under the same configuration key, and will check that all three are provided if the key is present.

// previously
const customCreateApi = buildCreateApi(
  coreModule(),
  reactHooksModule({
    useDispatch: createDispatchHook(MyContext),
    useSelector: createSelectorHook(MyContext),
    useStore: createStoreHook(MyContext),
  })
)

// now
const customCreateApi = buildCreateApi(
  coreModule(),
  reactHooksModule({
    hooks: {
      useDispatch: createDispatchHook(MyContext),
      useSelector: createSelectorHook(MyContext),
      useStore: createStoreHook(MyContext),
    },
  })
)

Deprecated Options Removed

Several other options were previously marked as deprecated, and have been removed. We've also removed polyfills like the AbortController polyfill.

TypeScript Changes

configureStore field order for middleware matters

If you are passing both the middleware and enhancers fields to configureStore, the middleware field must come first in order for internal TS inference to work properly.

Non-default middleware/enhancers must use Tuple

We've seen many cases where users passing the middleware parameter to configureStore have tried spreading the array returned by getDefaultMiddleware(), or passed an alternate plain array. This unfortunately loses the exact TS types from the individual middleware, and often causes TS problems down the road (such as dispatch being typed as Dispatch<AnyAction> and not knowing about thunks).

getDefaultMiddleware() already used an internal MiddlewareArray class, an Array subclass that had strongly typed .concat/prepend() methods to correctly capture and retain the middleware types.

We've renamed that type to Tuple, and configureStore's TS types now require that you must use Tuple if you want to pass your own array of middleware:

import { configureStore, Tuple } from '@reduxjs/toolkit'

configureStore({
  reducer: rootReducer,
  middleware: (getDefaultMiddleware) => new Tuple(additionalMiddleware, logger),
})

(Note that this has no effect if you're using RTK with plain JS, and you could still pass a plain array here.)

This same restriction applies to the enhancers field.

Entity adapter type updates

createEntityAdapter now has an Id generic argument, which will be used to strongly type the item IDs anywhere those are exposed. Previously, the ID field type was always string | number. TS will now try to infer the exact type from either the .id field of your entity type, or the selectId return type. You could also fall back to passing that generic type directly. If you use the EntityState<Data, Id> type directly, you must supply both generic arguments!

The .entities lookup table is now defined to use a standard TS Record<Id, MyEntityType>, which assumes that each item lookup exists by default. Previously, it used a Dictionary<MyEntityType> type, which assumed the result was MyEntityType | undefined. The Dictionary type has been removed.

If you prefer to assume that the lookups might be undefined, use TypeScript's noUncheckedIndexedAccess configuration option to control that.

New Features

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

The Redux core has always included combineReducers, which takes an object full of "slice reducer" functions and generates a reducer that calls those slice reducers. RTK's createSlice generates slice reducers + associated action creators, and we've taught the pattern of exporting individual action creators as named exports and the slice reducer as a default export. Meanwhile, we've never had official support for lazy-loading reducers, although we've had sample code for some "reducer injection" patterns in our docs.

This release includes a new combineSlices API that is designed to enable lazy-loading of reducers at runtime. It accepts individual slices or an object full of slices as arguments, and automatically calls combineReducers using the sliceObject.name field as the key for each state field. The generated reducer function has an additional .inject() method attached that can be used to dynamically inject additional slices at runtime. It also includes a .withLazyLoadedSlices() method that can be used to generate TS types for reducers that will be added later. See #2776 for the original discussion around this idea.

For now, we are not building this into configureStore, so you'll need to call const rootReducer = combineSlices(.....) yourself and pass that to configureStore({reducer: rootReducer}).

Basic usage: a mixture of slices and standalone reducers passed to combineSlices

const stringSlice = createSlice({
  name: 'string',
  initialState: '',
  reducers: {},
})

const numberSlice = createSlice({
  name: 'number',
  initialState: 0,
  reducers: {},
})

const booleanReducer = createReducer(false, () => {})

const api = createApi(/*  */)

const combinedReducer = combineSlices(
  stringSlice,
  {
    num: numberSlice.reducer,
    boolean: booleanReducer,
  },
  api
)
expect(combinedReducer(undefined, dummyAction())).toEqual({
  string: stringSlice.getInitialState(),
  num: numberSlice.getInitialState(),
  boolean: booleanReducer.getInitialState(),
  api: api.reducer.getInitialState(),
})

Basic slice reducer injection

// Create a reducer with a TS type that knows `numberSlice` will be injected
const combinedReducer =
  combineSlices(stringSlice).withLazyLoadedSlices<
    WithSlice<typeof numberSlice>
  >()

// `state.number` doesn't exist initially
expect(combinedReducer(undefined, dummyAction()).number).toBe(undefined)

// Create a version of the reducer with `numberSlice` injected (mainly useful for types)
const injectedReducer = combinedReducer.inject(numberSlice)

// `state.number` now exists, and injectedReducer's type no longer marks it as optional
expect(injectedReducer(undefined, dummyAction()).number).toBe(
  numberSlice.getInitialState()
)

// original reducer has also been changed (type is still optional)
expect(combinedReducer(undefined, dummyAction()).number).toBe(
  numberSlice.getInitialState()
)

selectors field in createSlice

The existing createSlice API now has support for defining selectors directly as part of the slice. By default, these will be generated with the assumption that the slice is mounted in the root state using slice.name as the field, such as name: "todos" -> rootState.todos. Additionally, there's now a slice.selectSlice method that does that default root state lookup.

You can call sliceObject.getSelectors(selectSliceState) to generate the selectors with an alternate location, similar to how entityAdapter.getSelectors() works.

const slice = createSlice({
  name: 'counter',
  initialState: 42,
  reducers: {},
  selectors: {
    selectSlice: (state) => state,
    selectMultiple: (state, multiplier: number) => state * multiplier,
  },
})

// Basic usage
const testState = {
  [slice.name]: slice.getInitialState(),
}
const { selectSlice, selectMultiple } = slice.selectors
expect(selectSlice(testState)).toBe(slice.getInitialState())
expect(selectMultiple(testState, 2)).toBe(slice.getInitialState() * 2)

// Usage with the slice reducer mounted under a different key
const customState = {
  number: slice.getInitialState(),
}
const { selectSlice, selectMultiple } = slice.getSelectors(
  (state: typeof customState) => state.number
)
expect(selectSlice(customState)).toBe(slice.getInitialState())
expect(selectMultiple(customState, 2)).toBe(slice.getInitialState() * 2)

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:

// Declare the thunk separately
const fetchUserById = createAsyncThunk(
  'users/fetchByIdStatus',
  async (userId: number, thunkAPI) => {
    const response = await userAPI.fetchById(userId)
    return response.data
  }
)

const usersSlice = createSlice({
  name: 'users',
  initialState,
  reducers: {
    // standard reducer logic, with auto-generated action types per reducer
  },
  extraReducers: (builder) => {
    // Add reducers for additional action types here, and handle loading state as needed
    builder.addCase(fetchUserById.fulfilled, (state, action) => {
      state.entities.push(action.payload)
    })
  },
})

Many users have told us that this separation feels awkward.

We've wanted to include a way to define thunks directly inside of createSlice, and have played around with various prototypes. There were always two major blocking issues, and a secondary concern:

It wasn't clear what the syntax for declaring a thunk inside should look like.
Thunks have access to getState and dispatch, but the RootState and AppDispatch types are normally inferred from the store, which in turn infers it from the slice state types. Declaring thunks inside createSlice would cause circular type inference errors, as the store needs the slice types but the slice needs the store types. We weren't willing to ship an API that would work okay for our JS users but not for our TS users, especially since we want people to use TS with RTK.
You can't do synchronous conditional imports in ES modules, and there's no good way to make the createAsyncThunk import optional. Either createSlice always depends on it (and adds that to the bundle size), or it can't use createAsyncThunk at all.

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.
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 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).

Here's what the new callback syntax looks like:

const createSliceWithThunks = buildCreateSlice({
  creators: { asyncThunk: asyncThunkCreator },
})

const todosSlice = createSliceWithThunks({
  name: 'todos',
  initialState: {
    loading: false,
    todos: [],
    error: null,
  } as TodoState,
  reducers: (create) => ({
    // A normal "case reducer", same as always
    deleteTodo: create.reducer((state, action: PayloadAction<number>) => {
      state.todos.splice(action.payload, 1)
    }),
    // A case reducer with a "prepare callback" to customize the action
    addTodo: create.preparedReducer(
      (text: string) => {
        const id = nanoid()
        return { payload: { id, text } }
      },
      // action type is inferred from prepare callback
      (state, action) => {
        state.todos.push(action.payload)
      }
    ),
    // An async thunk
    fetchTodo: create.asyncThunk(
      // Async payload function as the first argument
      async (id: string, thunkApi) => {
        const res = await fetch(`myApi/todos?id=${id}`)
        return (await res.json()) as Item
      },
      // An object containing `{pending?, rejected?, fulfilled?, settled?, options?}` second
      {
        pending: (state) => {
          state.loading = true
        },
        rejected: (state, action) => {
          state.error = action.payload ?? action.error
        },
        fulfilled: (state, action) => {
          state.todos.push(action.payload)
        },
        // settled is called for both rejected and fulfilled actions
        settled: (state, action) => {
          state.loading = false
        },
      }
    ),
  }),
})

// `addTodo` and `deleteTodo` are normal action creators.
// `fetchTodo` is the async thunk
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 is provided.

npx @reduxjs/rtk-codemods createSliceReducerBuilder ./src/features/todos/slice.ts

"Dynamic middleware" middleware

A Redux store's middleware pipeline is fixed at store creation time and can't be changed later. We have seen ecosystem libraries that tried to allow dynamically adding and removing middleware, potentially useful for things like code splitting.

This is a relatively niche use case, but we've built our own version of a "dynamic middleware" middleware. Add it to the Redux store at setup time, and it lets you add middleware later at runtime. It also comes with a React hook integration that will automatically add a middleware to the store and return the updated dispatch method..

import { createDynamicMiddleware, configureStore } from '@reduxjs/toolkit'

const dynamicMiddleware = createDynamicMiddleware()

const store = configureStore({
  reducer: {
    todos: todosReducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().prepend(dynamicMiddleware.middleware),
})

// later
dynamicMiddleware.addMiddleware(someOtherMiddleware)

configureStore adds autoBatchEnhancer by default

In v1.9.0, we added a new autoBatchEnhancer that delays notifying subscribers briefly when multiple "low-priority" actions are dispatched in a row. This improves perf, as UI updates are typically the most expensive part of the update process. RTK Query marks most of its own internal actions as "low-pri" by default, but you have to have the autoBatchEnhancer added to the store to benefit from that.

We've updated configureStore to add the autoBatchEnhancer to the store setup by default, so that users can benefit from the improved perf without needing to manually tweak the store config themselves.

entityAdapter.getSelectors accepts a createSelector function

entityAdapter.getSelectors() 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.

Next.js Setup Guide

We now have a docs page that covers how to set up Redux properly with Next.js. We've seen a lot of questions around using Redux, Next, and the App Router together, and this guide should help provide advice.

(At this time, the Next.js with-redux example is still showing outdated patterns - we're going to file a PR shortly to update that to match our docs guide.)

What's Changed

Remove legacy object syntax for reducers
Upgrade build tooling
Migrate the RTK package to be full ESM
Migrate RTK test suite from Jest to Vitest
Fix type errors after upgrading to Redux 5 alpha
Bump Redux dep to 5.0.0-alpha.2
Test published artifacts in CI
Merge RTK CI examples into v2.0-integration
Add arethetypeswrong automated CLI check
Update tip regarding overrideExisting to match actual behaviour
Add attw CLI option to treat problems as non-errors
Rework build setup and hopefully fix ESM compat issues
Switch build setup from a custom ESBuild+TS script to tsup
Use original instead of immer draft for perf
Enable enhanceEndpoints.transformResponse to override ResultType
Fix global responseHandler being used in fetchBaseQuery
Reset internalState.currentSubscriptions on resetApiState
Bump deps and mark subscriptionUpdated as autobatched
Redux 5alpha5
Add isAction helper function, and ensure listener middleware only runs for actions
Allow inference of enhancer state extensions, and fix inference when using callback form
combineSlices implementation
Bump Immer to 10.0 final
Allow partial preloaded state for combined slice reducer and update devDeps
Ensure it's only possible to pass all or none of the hooks to reactHooksModule
removed
Remove remaining deprecated exports
Create action creator middleware
Restore query status types
Implement auto fork joining
types: Make it easier to wrap createAsyncThunk
Fixed Stackoverflow bug if children prop is a ref to root/parent object
Add getDefaultEnhancers callback, and add autoBatchEnhancer to defaults.
Update to Redux alpha 6
Remove toString override from action creators, in favour of explicit .type field.
Add "creator callback" syntax to slice reducer field, to allow for async thunk creation
API for adding middleware dynamically
Add Id type parameter in createEntityAdapter
Require usage of Tuple in TS
Require that enhancers is a callback
Fix invalid createEntityAdapter call
Use Record<EntityId, T> instead of Dictionary<T>
Fix inference for reducers without actions specified
Prefer UnknownAction and Action to AnyAction
Allow passing a createSelector instance to adapter.getSelectors
Add required type parameter to EntityState in docs
Fix syntax for users with noPropertyAccessFromIndexSignature enabled
Fix TransformedResponse type to unwrap promise
Fix multiple TS build and packaging issues
Default export of the module has or is using private name type error when using latest alpha/beta
RTK Query: Resolve type portability issues
RTKQuery React: Resolved declare module pathing for Node16
removed
2448: Remove abort controller polyfill
Throw error when type is empty in builder.addCase
Updated type references to resolve portable types issue
Add option to update provided tags
Add selectCachedArgsForQuery util
Remove Request.clone() usage in fetchBaseQuery
Try working around TS 4.1 mismatch
Optimize bundles for RTK 2.0
Work around known TS bug with type inference
removed
Remove middleware array option
Warn for and migrate old options and require all hooks
Feature/entity adapter draftable entity state
Write create callback codemod
Copy of "Work around known TS bug with type inference #3761"
Rework named hooks type (v1.9)
Rewrite HooksWithUniqueNames type (v2.0)
Adds the option of generating real TS enums instead of string unions
Adjust snake case regex
Update error message: name of action type
Created listenerApi.cancel()
Add listenerApi.throwIfCancelled()
Add settled matcher for createAsyncThunk
Rewrite RTKQ internal subscription lookups and subscription syncing
Keep subscription on data while query is running
Stop re-exporting autotrackMemoize
Delayed tag invalidations
Output selector fields are currently missing in selector functions created using createDraftSafeSelector.
createDynamicMiddleware bike shedding
Allow passing selector creators with different memoize options to getSelectors
Add selectSlice to slice instance
Throw an error if ApiProvider is nested inside a normal Provider.
Update store configuration using configureStore in createSlice.mdx
Create standardised methods of modifying reducer handler context.
Require calling buildCreateSlice to use create.asyncThunk
Restore the toString override, but keep it out of the docs.
Selector housekeeping - emplace and unwrapped
Update build tooling for 2.0
Export EndpointBuilder
Update to Redux core v5 rc1 and replace isAction/isPlainObject with core counterparts
Drop "ESM modern dev" build and rename "ESM prod" to "browser"
Fix isFSA import and avoid unnecessary type param
Avoid passing an identity function to createSelector

1.9.7

4 Oct 2023

Copy of "Work around known TS bug with type inference #3761"
Rework named hooks type (v1.9)

1.9.6

24 Sep 2023

Create action creator middleware
Implement auto fork joining
types: Make it easier to wrap createAsyncThunk

This bugfix release adds a new dev-mode middleware to catch accidentally dispatching an action creator, adds a new listener middleware option around waiting for forks, adds a new option to update provided tags when updateQueryData is used, reworks internal types to better handle uses with TS declaration output, and fixes a variety of small issues.

Changelog

Action Creator Dev Check Middleware

RTK already includes dev-mode middleware that check for the common mistakes of accidentally mutating state and putting non-serializable values into state or actions.

Over the years we've also seen a semi-frequent error where users accidentally pass an action creator reference to dispatch, instead of calling it and dispatching the action it returns.

We've added another dev-mode middleware that specifically catches this error and warns about it.

Additional Options

The listener middleware's listenerApi.fork() method now has an optional autoJoin flag that can be used to keep the effect from finishing until all active forked tasks have completed.

updateQueryData now has an updateProvidedTags option that will force a recalculation of that endpoint's provided tags. It currently defaults to false, and we'll likely turn that to true in the next major.

Other Fixes

The builder.addCase method now throws an error if a type string is empty.

fetchBaseQuery now uses an alternate method to clone the original Request in order to work around an obscure Chrome bug.

The immutability middleware logic was tweaked to avoid a potential stack overflow.

Types Changes

The internal type imports have been reworked to try to fix "type portability" issues when used in combination with TS declaration outputs.

A couple additional types were exported to help with wrapping createAsyncThunk.

What's Changed

Create action creator middleware
Implement auto fork joining
types: Make it easier to wrap createAsyncThunk
Fixed Stackoverflow bug if children prop is a ref to root/parent object
Fix TransformedResponse type to unwrap promise
Throw error when type is empty in builder.addCase
Updated type references to resolve portable types issue
Add option to update provided tags
Remove Request.clone() usage in fetchBaseQuery
Try working around TS 4.1 mismatch

1.9.5

18 Apr 2023

Update to latest remark-typescript-tools
Add isAction helper function, and ensure listener middleware only runs for actions
Allow inference of enhancer state extensions, and fix inference when using callback form

1.9.4

17 Apr 2023

Test published artifacts in CI
Use Git revision in version and add Node CI examples
Add arethetypeswrong automated CLI check

1.9.3

21 Feb 2023

Revert "clear data on skip" back to its original behavior
Use a WeakMap cache for query arg serialization for perf

1.9.2

28 Jan 2023

Fix CaseReducer to infer from argument, not return value
fetchBaseQuery | Add jsonReplacer param
Support RegExp in ignoredPaths/ignoredActionPaths

1.9.1

30 Nov 2022

Fix createAsyncThunk.withTypes
Update timer polyfills to work in more environments
Retry now checks whether potential retry counts are undefined, rather than boolean, in order to avoid filtering out 0's

This bugfix release fixes assorted issues that were reported with RTK 1.9.0, and adds a few additional requested tweaks and improvements.

Changelog

Fixes

The createAsyncThunk.withTypes function was fully broken (it type-checked correctly, but pointed to the wrong function due to a name shadowing issue). That now works correctly.

The maxRetries option for RTKQ was inadvertently filtering out 0 values, and those are now accepted.

fulfillWithValue had incorrect types that made it appear as if the data was nested an additional level deeper. The types are now correct.

The ActionCreatorWithoutPayload type was tweaked to force an error when an action creator is accidentally called with an argument, which happens in cases like onClick={todoAdded}. This avoids accidentally passing values like React event objects as the payload.

Timer handling for batchActions and autoBatchEnhancer now works in more JS runtime environments.

Other Changes

The TagDescription type is now exported from RTKQ.

API endpoints now have a .name field containing the endpoint name, such as "getPokemon".

Calling promise.abort() on a createAsyncThunk promise before an async condition resolves will now be treated as if the condition itself returned false, bailing out and not dispatching anything.

The merge option now receives a third argument containing {arg, baseQueryMeta, fulfilledTimeStamp, requestId}, in case that info is useful in deciding how to merge.

The @reduxjs/rtk-codemods package has been updated to fix cases where the createSliceBuilder codemod didn't preserve fields with function variable arguments, like [todoAdded]: adapter.addOne. That package has been updated to v0.0.3.

What's Changed

Fix createAsyncThunk.withTypes
Update timer polyfills to work in more environments
Retry now checks whether potential retry counts are undefined, rather than boolean, in order to avoid filtering out 0's
Fix multiple small issues with 1.9
fulfillWithValue should infer return value
Fix Identifier/MemberExpression values in createSliceBuilder codemod
Additional 1.9.1 fixes

1.9.0

4 Nov 2022

deprecated
getRunningQueryThunk(endpointName, queryArgs)
deprecated
getRunningMutationThunk(endpointName, fixedCacheKeyOrRequestId)
deprecated
getRunningQueriesThunk()

This feature release adds several new options for RTK Query's createApi and fetchBaseQuery APIs, adds a new upsertQueryData util, rewrites RTKQ's internals for improved performance, adds a new autoBatchEnhancer, deprecates the "object" syntax for createReducer and createSlice.extraReducers, deprecates and removes broken utils for getting running query promises, improves TS inference, exports additional types, and fixes a number of reported issues.

npm i @reduxjs/toolkit@latest

yarn add @reduxjs/toolkit@latest

We plan to start work on RTK 2.0 in the next few weeks. RTK 2.0 will focus on dropping legacy build compatibility and deprecated APIs, with some potential new features. See the linked discussion thread and give us feedback on ideas!

Deprecations and Removals

Object Argument for createReducer and createSlice.extraReducers

RTK's createReducer API was originally designed to accept a lookup table of action type strings to case reducers, like { "ADD_TODO" : (state, action) => {} }. We later added the "builder callback" form to allow more flexibility in adding "matchers" and a default handler, and did the same for createSlice.extraReducers.

We intend to remove the "object" form for both createReducer and createSlice.extraReducers in RTK 2.0. The builder callback form is effectively the same number of lines of code, and works much better with TypeScript.

Starting with this release, RTK will print a one-time runtime warning for both createReducer and createSlice.extraReducers if you pass in an object argument.

As an example, this:

const todoAdded = createAction('todos/todoAdded');

createReducer(initialState, {
  [todoAdded]: (state, action) => {}
})

createSlice({
  name,
  initialState,
  reducers: {/* case reducers here */},
  extraReducers: {
    [todoAdded]: (state, action) => {}
  }
})

should be migrated to:

createReducer(initialState, builder => {
  builder.addCase(todoAdded, (state, action) => {})
})

createSlice({
  name,
  initialState,
  reducers: {/* case reducers here */},
  extraReducers: builder => {
    builder.addCase(todoAdded, (state, action) => {})
  }
})

Codemods for Deprecated Object Reducer Syntax

To simplify upgrading codebases, we've published a set of codemods that will automatically transform the deprecated "object" syntax into the equivalent "builder" syntax.

The codemods package is available on NPM as @reduxjs/rtk-codemods. It currently contains two codemods: createReducerBuilder and createSliceBuilder.

To run the codemods against your codebase, run npx @reduxjs/rtk-codemods <TRANSFORM NAME> path/of/files/ or/some**/*glob.js.

Examples:

npx @reduxjs/rtk-codemods createReducerBuilder ./src

npx @reduxjs/rtk-codemods createSliceBuilder ./packages/my-app/**/*.ts

We also recommend re-running Prettier on the codebase before committing the changes.

These codemods should work, but we would greatly appreciate testing and feedback on more real-world codebases!

Object reducer codemod before/after examples Before:

createReducer(initialState, {
  [todoAdded1a]: (state, action) => {
    // stuff
  },
  [todoAdded1b]: (state, action) => action.payload,
});

const slice1 = createSlice({
  name: "a",
  initialState: {},
  extraReducers: {
    [todoAdded1a]: (state, action) => {
      // stuff
    },
    [todoAdded1b]: (state, action) => action.payload,
  }
})

After:

createReducer(initialState, (builder) => {
  builder.addCase(todoAdded1a, (state, action) => {
    // stuff
  });

  builder.addCase(todoAdded1b, (state, action) => action.payload);
})

const slice1 = createSlice({
  name: "a",
  initialState: {},

  extraReducers: (builder) => {
    builder.addCase(todoAdded1a, (state, action) => {
      // stuff
    });

    builder.addCase(todoAdded1b, (state, action) => action.payload);
  }
})

getRunningOperationPromises Deprecation and Replacement

In v1.7.0, we added an api.util.getRunningOperationPromises() method for use with SSR scenarios, as well as a singular getRunningOperationPromise() method intended for possible use with React Suspense.

Unfortunately, in #2477 we realized that both those methods have a fatal flaw - they do not work with multiple stores in SSR.

As of this release, we are immediately marking getRunningOperationPromises() as deprecated and discouraging its use before we remove it completely in RTK 2.0! It will now throw both runtime and compile errors in development to enforce moving away from using it. However, we are leaving its existing behavior in production builds to avoid actual breakage.

The getRunningOperationPromise() util was experimental, and as far as we can tell not actually being used by anyone, so we are removing getRunningOperationPromise completely in this release.

As replacements, RTKQ now includes four new thunks attached to api.util:

deprecated
getRunningQueryThunk(endpointName, queryArgs)
deprecated
getRunningMutationThunk(endpointName, fixedCacheKeyOrRequestId)
deprecated
getRunningQueriesThunk()
deprecated
getRunningMutationsThunk()

Usages would typically change like this:

-await Promise.all(api.util.getRunningOperationPromises())
+await Promise.all(dispatch(api.util.getRunningQueriesThunk()))

Changelog

New RTK Query createApi Options

createApi endpoints now have several additional options that can be passed in, some of which are intended to work together.

merge Option

RTKQ was built around the assumption that the server is the source of truth, and every refetch replaces the cached data on the client. There are use cases when it would be useful to merge an incoming response into the existing cached data instead, such as pagination or APIs that return varying results over time.

Query endpoints can now accept a merge(cachedData, responseData) callback that lets you do Immer-powered "mutations" to update the existing cached data instead of replacing it entirely.

Since RTKQ assumes that each response per key should replace the existing cache entry by default, the merge option is expected to be used with the serializeQueryArgs and forceRefetch options, as described below.

serializeQueryArgs Option

RTK Query always serializes the cache key value, and uses the string as the actual key for storing the cache entry. The default serialization is the name of the endpoint, plus either the primitive value or a stable-serialized object. An example might be state.api.queries['getPokemon("pikachu")'].

RTKQ already supported customization of this serialization behavior at the createApi level. Now, each endpoint can specify its own serializeQueryArgs method.

The per-endpoint serializeQueryArgs may return either a string, an object, a number, or a boolean. If it's a string, that value will be used as-is. Otherwise, the return value will be run through the default serialization logic. This simplifies the common case of stripping out a couple unwanted object fields from the cache key.

This option serves two main purposes: leaving out values that are passed in to an endpoint but not really part of the "key" conceptually (like a socket or client instance), and altering cache key behavior to use a single entry for the endpoint (such as in an infinite loading / pagination scenario).

Also, the defaultSerializeQueryArgs util is now exported.

    getPost: build.query<Post, { id: string; client: MyApiClient }>({
      queryFn: async ({ id, client }) => {
        const post = await client.fetchPost(id)
        return { data: post }
      },
      serializeQueryArgs: ({ queryArgs, endpointDefinition, endpointName }) => {
        const { id } = queryArgs
        // This can return a string, an object, a number, or a boolean.
        // If it returns an object, number or boolean, that value
        // will be serialized automatically via `defaultSerializeQueryArgs`
        return { id } // omit `client` from the cache key

        // Alternately, you can use `defaultSerializeQueryArgs`:
        // return defaultSerializeQueryArgs({
        //   endpointName,
        //   queryArgs: { id },
        //   endpointDefinition
        // })
        // Or  create and return a string yourself:
        // return `getPost(${id})`
      },
    }),

forceRefresh option

Sometimes you may want to force a refetch, even though RTKQ thinks that the serialized query args haven't changed and there's already a fulfilled cache entry.

This can be used to force RTKQ to actually refetch. One expected use case is an "infinite pagination" scenario where there is one cache entry for the endpoint, different page numbers are given as query args, and the incoming responses are merged into the existing cache entry:

    listItems: build.query<string[], number>({
      query: (pageNumber) => `/listItems?page=${pageNumber}`,
      // Only have one cache entry because the arg always maps to one string
      serializeQueryArgs: ({ endpointName }) => {
        return endpointName
      },
      // Always merge incoming data to the cache entry
      merge: (currentCache, newItems) => {
        currentCache.push(...newItems)
      },
      // Refetch when the page arg changes
      forceRefetch({ currentArg, previousArg }) {
        return currentArg !== previousArg
      },
    }),

transformErrorResponse Option

Similar to transformResponse, endpoints can now specify a transformErrorResponse option as well.

upsertQueryData Util

RTKQ already has an updateQueryData util to synchronously modify the contents of an existing cache entry, but there was no way to create a new cache entry and its metadata programmatically.

This release adds a new api.util.upsertQueryData API that allows creating a cache entry + its data programmatically. As with the other util methods, this is a thunk that should be dispatched, and you should pass in the exact cache key arg and complete data value you want to insert:

dispatch(
  api.util.upsertQueryData('post', '3', {
    id: '3',
    title: 'All about cheese.',
    contents: 'I love cheese!',
   })
)

The dispatch acts like all other RTKQ requests, so the process is async, and the thunk returns a promise that resolves when the upsert is complete.

RTK Query Performance Improvements

We've significantly rewritten RTK Query's internal implementation to improve performance, especially in cases where many components with query hooks mount at the same time. The middleware has been "flattened" and runs fewer internal checks against each action, subscription updates are grouped together, and some unnecessary memoized selectors have been removed. One consequence is that forgetting to add the RTKQ middleware now throws an error instead of logging a warning.

Overall, RTK Query processing time should be noticeably faster than it was in 1.8.

RTK Query also can take advantage of the new "auto-batch enhancer" (described below) for some additional perf optimization, and we recommend adding that to your Redux store configuration.

fetchBaseQuery Options

fetchBaseQuery has several new options for processing requests:

You can now specify a timeout option for both individual endpoints and fetchBaseQuery . If provided, requests that take longer than this value will automatically abort.

fetchBaseQuery now supports passing the responseHandler and validateStatus options directly to fetchBaseQuery itself, in addition to accepting it as part of specific endpoints. If provided, these options will be applied as defaults to all requests for that API, which simplifies using them on many endpoints. Providing them for endpoints overrides the global option.

You can now specify a jsonContentType string that will be used to set the content-type header for a request with a jsonifiable body that does not have an explicit content-type header. Defaults to "application/json".

You can now specify a isJsonContentType callback that checks to see if the request body or response body should be stringified. The default looks for values like "application/json" and "application/vnd.api+json". You can also now specify responseHandler: 'content-type' to have RTKQ automatically check to see whether a response should be treated as text or JSON.

The prepareHeaders method can now return void and does not have to return headers.

Other RTK Query Changes

The refetch() methods now return a promise that can be awaited.

Query endpoints can now accept a retryCondition callback as an alternative to maxRetries. If you provide retryCondition, it will be called to determine if RTKQ should retry a failed request again.

New Auto-Batching Store Enhancer

There are several different ways to "batch actions" with Redux stores, ranging from reducers to debounced subscriber notifications.

RTK now includes a new autoBatchEnhancer() store enhancer that uses a variation on the "debounced notification" approach, inspired by React's technique of batching renders and determining if an update is low-priority or high-priority.

The enhancer looks for any actions tagged with an action.meta[SHOULD_AUTOBATCH] = true flag, and delays notifying subscribers until a queued callback runs. This means that if multiple "auto-batched" actions are dispatched in a row, there will be only one subscriber notification. However, if any "normal-priority" action without that flag are dispatched before the queued callback runs, the enhancer will notify subscribers immediately instead and ignore the callback.

This allows Redux users to selectively tag certain actions for effective batching behavior, making this purely opt-in on a per-action basis, while retaining normal notification behavior for all other actions.

The enhancer defaults to using requestAnimationFrame, but can also be configured to use queueMicrotask to run at the end of an event loop tick, setTimeout, or a user-provided callback.

RTK Query's internals have been updated to mark several key actions as batchable. While the enhancer is purely opt-in, benchmarks indicate that it can help speed up UI performance with RTK Query, especially when rendering many components with query hooks. We recommend adding this enhancer to your store setup if you're using RTK Query:

  const store = configureStore({
  reducer,
  enhancers: (existingEnhancers) => {
    // Add the autobatch enhancer to the store setup
    return existingEnhancers.concat(autoBatchEnhancer())
  },
})

Additionally, there's a prepareAutoBatched util that can be used to help add the SHOULD_AUTOBATCH flag to actions, designed for use with createSlice:

const counterSlice = createSlice({
  name: 'counter',
  initialState: { value: 0 } as CounterState,
  reducers: {
    incrementBatched: {
      // Batched, low-priority
      reducer(state) {
        state.value += 1
      },
      // Use the `prepareAutoBatched` utility to automatically
      // add the `action.meta[SHOULD_AUTOBATCH]` field the enhancer needs
      prepare: prepareAutoBatched<void>(),
    },
    // Not batched, normal priority
    decrementUnbatched(state) {
      state.value -= 1
    },
  },
})

TypeScript Improvements

RTK 1.9 now requires TS 4.2 or greater, and supports through TS 4.9.

The action type strings generated by createAction are now full TS template literals when possible.

There's now a createAsyncThunk.withTypes() method that creates a "pre-typed" version of createAsyncThunk with types like {state, dispatch, extra} baked in. This can be used to simplify customizing createAsyncThunk with the right types once during app setup.

RTK Query now exports TS types for "pre-typed hook results", for cases when you want to wrap the query/mutation hooks in your own code. Additionally, RTKQ also exports BaseQueryApi and exposes TS-only types for endpoint definitions.

configureStore now correctly infers changes to the store shape from any store enhancers, such as adding actual extra fields to store.

RTK now exports additional types from redux-thunk.

Bug Fixes

Manually initiated RTKQ promises should resolve correctly.

Previous API tags are removed before adding new ones, instead of accidentally merging them together.

invalidateTags works correctly when dealing with persisted query state.

What's Changed

Add isJsonContentType predicate to fetchBaseQuery
Add jsonContentType to fetchBaseQuery options
Add ThunkMiddleware to the re-exported types from redux-thunk
Add timeout option to fetchBaseQuery
createSlice: Use template literal types for action type
Add types for manually typing hook results in userland code
Add 'content-type' ResponseHandler
Feature : endpoint-specific args serializers
RFC: Add "merge" functionality
deprecated
Add runtime deprecation warning for reducer object notation
Add the ability to type StoreEnhancers
Batch RTKQ "subscribe on reject" actions, and improve cache collection timer handling
Add transformErrorReponse to rtkq endpoints
Fix manually initiate()d rtk-query promises
Implement codemods for createReducer and createSlice builder
RFC: Expose endpoint types
Add createAsyncThunk.withTypes
Return promise from query result & hook refetch
Retry condition by http error response
Implemented upsertQueryData functionality per #1720 #2007
Consolidate RTKQ middleware to simplify stack size
Try fixing createAsyncThunk issues with TS 4.8
Fix assorted issues with the RTKQ middleware refactor
Fix upsertQueryData race situations
Fix upsert
Export the BaseQueryApi interface from rtk-query so it can be used as a type in TypeScript without importing from dist/.
Fix retryCondition error.
Export ToolkitStore interface from configureStore
Reset dispatchQueued variable after flushing
Add forceRefetch to QueryExtraOptions
Speed up subscription behavior by tracking state in middleware
prepareHeaders does not need to return headers any more
Add codemods-cli and rewrite "object reducer" codemods
Remove alpha compatibility fallbacks
Fix skipToken behaviour in useQueryState
fetchBaseQuery: allow headers option
Replace getRunningOperationPromise(s) with getRunning(Query|Queries|Mutation|Mutations)Thunk
General pre-1.9-beta cleanup
Convert "middleware not registered" warning into a full error
Rework endpoint serializeQueryArgs to allow object/number returns
Allow for global responseHandler and validateStatus configuration
Fix refetches when sQA returns same value and queryArgs are object
Add an auto-batching enhancer that delays low-pri notifications and use with RTKQ
Check middleware registration directly to avoid persistence issues
Fix "running thunks" types and remove unnecessary RTKQ selectors
Make autobatching notification queueing configurable
Hopefully final v1.9 tweaks

1.8.6

9 Oct 2022

removed
Remove previous api tags before adding new provided tags
Fix the dispatch type inference to correctly handle read-only middleware arrays
toolkit: Export "ThunkMiddleware" from redux-thunk

1.8.5

19 Aug 2022

Prevent keepUnusedDataFor values from overflowing setTimeout counter
Remove typeof undefined checks where not necessary 🐃🪒
Update RDT options types, and export those + AnyListenerPredicate

1.8.4

11 Aug 2022

Prevent duplicate ids when updating id of an element with the id of an existing element
ApiProvider: Correctly register listeners, allow to disable listeners
Update devtools options TS types based on RDT 3.0

This bugfix release adds exported TS types for RTKQ hooks for use in wrapping logic, adds useDebugValue to the hooks to improve display in the React DevTools, updates the inlined types for the Redux DevTools options, and fixes an issue in createEntityAdapter that could result in duplicate IDs being stored.

Changelog

RTKQ Hook Result Types

RTK's types heavily rely on inference to minimize the amount of type info users have to provide. However, this can also make it difficult to write functions that wrap calls to RTK APIs.

Some users have asked to have types that help them write "higher-order hooks". RTK now exports types that represent "the return object for a query/mutation hook with a given value": TypedUseQueryHookResult and TypedUseMutationResult. Both require <ResultType, QueryArg, BaseQuery> as generics, like this:

const baseQuery = fetchBaseQuery({url: "https://some.server"});

type CustomHookResult = TypedUseQueryHookResult<MyResultObject, MyArgObject, typeof baseQuery>

const useMyCustomHook = (arg: MyArgObject) : CustomHookResult => {
  return api.useGetSomeDataQuery(arg);
}

Redux DevTools Options Fixes

As of Redux DevTools 3.0, some of field names for custom DevTools options have changed to actionsAllowlist and actionsDenylist. Since we inline the types instead of having a separate dependency, we've updated our TS types to match that. No runtime behavior was changed.

Other Changes

RTKQ hooks now use useDebugValue to give a better preview of the current value in the React DevTools "Component" tab.

The <ApiProvider> component now does a better job of registering and cleaning up focus listeners.

Fixed a bug with createEntityAdapter that could allow duplicate IDs to be added depending on update parameters.

What's Changed

Prevent duplicate ids when updating id of an element with the id of an existing element
ApiProvider: Correctly register listeners, allow to disable listeners
Update devtools options TS types based on RDT 3.0
Typo in unhandled error message
Use useDebugValue in useQuery and useMutation hooks
Add types for manually typing hook results in userland code

1.8.3

30 Jun 2022

Add Missing Else to enhanceEndpoints Function
Check initial state is draftable before using immer to freeze it.
Check that body isJsonifiable before stringify

1.8.2

25 May 2022

Add type @remarks for configureStore's middleware
Fix the "map values transpilation" bug, in yet another place

1.8.1

31 Mar 2022

This release updates RTK's peer dependencies to accept React 18 as a valid version. This should fix installation errors caused by NPM's "install all the peer deps and error if they don't match" behavior.

1.8.0

27 Feb 2022

This release adds the new "listener" middleware, updates configureStore's types to better handle type inference from middleware that override dispatch return values, and updates our TS support matrix to drop support for TS < 4.1.

Changelog

New "Listener" Side Effects Middleware

RTK has integrated the thunk middleware since the beginning. However, thunks are imperative functions, and do not let you run code in response to dispatched actions. That use case has typically been covered with libraries like redux-saga (which handles side effects with "sagas" based on generator functions), redux-observable (which uses RxJS observables), or custom middleware.

We've added a new "listener" middleware to RTK to cover that use case. The listener middleware is created using createListenerMiddleware(), and lets you define "listener" entries that contain an "effect" callback with additional logic and a way to specify when that callback should run based on dispatched actions or state changes.

Conceptually, you can think of this as being similar to React's useEffect hook, except that it runs logic in response to Redux store updates instead of component props/state updates.

The listener middleware is intended to be a lightweight alternative to more widely used Redux async middleware like sagas and observables. While similar to thunks in level of complexity and concept, it can replicate some common saga usage patterns. We believe that the listener middleware can be used to replace most of the remaining use cases for sagas, but with a fraction of the bundle size and a much simpler API.

Listener effect callbacks have access to dispatch and getState, similar to thunks. The listener also receives a set of async workflow functions like take, condition, pause, fork, and unsubscribe, which allow writing more complex async logic.

Listeners can be defined statically by calling listenerMiddleware.startListening() during setup, or added and removed dynamically at runtime with special dispatch(addListener()) and dispatch(removeListener()) actions.

The API reference is available at:

redux-toolkit.js.org/api/createListenerMiddlewa…

Basic usage of the listener middleware looks like:

import { configureStore, createListenerMiddleware } from '@reduxjs/toolkit'

import todosReducer, {
  todoAdded,
  todoToggled,
  todoDeleted,
} from '../features/todos/todosSlice'

// Create the middleware instance and methods
const listenerMiddleware = createListenerMiddleware()

// Add one or more listener entries that look for specific actions.
// They may contain any sync or async logic, similar to thunks.
listenerMiddleware.startListening({
  actionCreator: todoAdded,
  effect: async (action, listenerApi) => {
    // Run whatever additional side-effect-y logic you want here
    console.log('Todo added: ', action.payload.text)

    // Can cancel other running instances
    listenerApi.cancelActiveListeners()

    // Run async logic
    const data = await fetchData()

    // Pause until action dispatched or state changed
    if (await listenerApi.condition(matchSomeAction)) {
      // Use the listener API methods to dispatch, get state,
      // unsubscribe the listener, start child tasks, and more
      listenerApi.dispatch(todoAdded('Buy pet food'))
      listenerApi.unsubscribe()
    }
  },
})

const store = configureStore({
  reducer: {
    todos: todosReducer,
  },
  // Add the listener middleware to the store.
  // NOTE: Since this can receive actions with functions inside,
  // it should go before the serializability check middleware
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().prepend(listenerMiddleware.middleware),
})

You can use it to write more complex async workflows, including pausing the effect callback until a condition check resolves, and forking "child tasks" to do additional work:

// Track how many times each message was processed by the loop
const receivedMessages = {
  a: 0,
  b: 0,
  c: 0,
}

const eventPollingStarted = createAction('serverPolling/started')
const eventPollingStopped = createAction('serverPolling/stopped')

listenerMiddleware.startListening({
  actionCreator: eventPollingStarted,
  effect: async (action, listenerApi) => {
    // Only allow one instance of this listener to run at a time
    listenerApi.unsubscribe()

    // Start a child job that will infinitely loop receiving messages
    const pollingTask = listenerApi.fork(async (forkApi) => {
      try {
        while (true) {
          // Cancellation-aware pause for a new server message
          const serverEvent = await forkApi.pause(pollForEvent())
          // Process the message. In this case, just count the times we've seen this message.
          if (serverEvent.type in receivedMessages) {
            receivedMessages[
              serverEvent.type as keyof typeof receivedMessages
            ]++
          }
        }
      } catch (err) {
        if (err instanceof TaskAbortError) {
          // could do something here to track that the task was cancelled
        }
      }
    })

    // Wait for the "stop polling" action
    await listenerApi.condition(eventPollingStopped.match)
    pollingTask.cancel()
  },
})

configureStore Middleware Type Improvements

Middleware can override the default return value of dispatch. configureStore tries to extract any declared dispatch type overrides from the middleware array, and uses that to alter the type of store.dispatch.

We identified some cases where the type inference wasn't working well enough, and rewrote the type behavior to be more correct.

TypeScript Support Matrix Updates

RTK now requires TS 4.1 or greater to work correctly, and we've dropped 4.0 and earlier from our support matrix.

Other Changes

The internal logic for the serializability middleware has been reorganized to allow skipping checks against actions, while still checking values in the state.

What's Changed

Since most of the implementation work on the middleware was done over the last few months, this list only contains the most recent PRs since 1.7.2. For details on the original use case discussions and the evolution of the middleware API over time, see:

PRs since 1.7.2:

Rewrite MiddlewareArray and gDM for better Dispatch inference
Change listener middleware API name and signature
alm: Add cancellation message to TaskAbortError, listenerApi.signal & forkApi.signal.
: missing type export
Reorganize serializable check conditions
alm: Prevent zombie listeners caused by forked tasks
Integrate the listener middleware into the RTK package
alm: Cancel forkApi.delay and forkApi.pause if listener is cancelled or completed
Enable cancelling active listeners when unsubscribing
v1.8.0 integration

1.7.2

3 Feb 2022

meta: Passes meta to result description functions [#1904]
Fix addMatcher typings
Pass baseQueryMeta into calculateProvidedBy

This release fixes a TS types bug with RTK Query generated selectors, makes the RTKQ structural sharing behavior configurable, adds an option to have the serializability middleware ignore all actions, and has several minor bugfixes and enhancements to RTK Query.

Changelog

RTK Query Selector TS Types Fix

Several users had reported that as of 1.7.0 selectors generated via apiSlice.endpoint.select() were failing to compile when used, with TS errors that looked like Type '{}' is missing the following properties from type 'CombinedState<>.

We've fixed the issue, and selectors should now compile correctly when used with TS.

Additional Configuration Options

RTK Query implements a technique called "structural sharing" to preserve existing object references if possible when data for an endpoint is re-fetched. RTKQ recurses over both data structures, and if the contents appear to be the same, keeps the existing values. That helps avoid potential unnecessary re-renders in the UI, because otherwise the entire re-fetched result would be new object references.

However, this update process can potentially take time depending on the size of the response. Endpoints can now be given a structuralSharing option that will turn that off to save on processing time:

    const api = createApi({
      baseQuery: fetchBaseQuery({ baseUrl: "https://example.com" }),
      endpoints: (build) => ({
        getEveryEntityInADatabase: build.query({
          query: () => ({ url: "/i-cant-paginate-data" }),
          structuralSharing: false,
        }),
      }),
    });

Additionally, the serializability check middleware can now be customized with an ignoreActions option to exempt all actions from being checked. This is an escape hatch and isn't recommended for most apps:

    const store = configureStore({
      reducer: rootReducer,
      middleware: (getDefaultMiddleware) =>
        getDefaultMiddleware({
          serializableCheck: {
            ignoreActions: true,
          },
        }),
    });

Other API Improvements

If an extraArgument was provided to the thunk middleware during store configuration, that value is now passed along to the prepareHeaders() function:

  const store = configureStore({
	reducer: rootReducer,
	middleware: (getDefaultMiddleware) =>
	  getDefaultMiddleware({
		thunk: {
		  extraArgument: { myCustomApiService },
		},
	  }),
  });

  // ..later on
  const api = createApi({
	baseQuery: fetchBaseQuery({
	  baseUrl: "https://example.com",
	  prepareHeaders: async (headers, { getState, extra }) => {
		const token = getState().auth.token;
		const somethingElse = await extra.myCustomApiService.someMethod();
		// do things with somethingElse
		return headers;
	  },
	}),
  });

The invalidatesTags/providesTags functions now receive the action.meta field as an argument, to help with potentially invalidating based on request/response headers.

Bug Fixes

refetchOnFocus now cleans up cache entries if a focus event is received and there are no active subscriptions, to avoid unnecessary requests.

Active polls are cleaned up when the last component for a given subscription unsubscribes.

The types for builder.addMatcher have been updated to support inference of guards without a type property.

What's Changed

meta: Passes meta to result description functions [#1904]
Fix addMatcher typings
Pass baseQueryMeta into calculateProvidedBy
Cleanup polls on unsubscribeQueryResult
Add extra to prepareHeaders, update documentation + tests
Fix reducerPath for query definitions
Update serialize documentation link
Refetch should not happen if no active subscribers
Add ignoreActions flag to serializable state middleware
RTKQ: Configurable structuralSharing on endpoints/queries/createApi

1.7.1

16 Dec 2021

Fix types for TS 4.5

1.7.0

10 Dec 2021

Updates RTK Query with support for SSR and rehydration
Allows sharing mutation results across components
Adds a new currentData field to query results

This feature release has a wide variety of API improvements:

Updates RTK Query with support for SSR and rehydration
Allows sharing mutation results across components
Adds a new currentData field to query results
Adds several new options for customizing endpoints and base queries
Adds support for async condition options in createAsyncThunk
Updates createSlice/createReducer to accept a "lazy state initializer" function
Updates createSlice to avoid potential circular dependency issues by lazy-building its reducer
Updates Reselect and Redux-Thunk to the latest versions with much-improved TS support and new selector customization options
Fixes a number of small code and types issues

npm i @reduxjs/toolkit@latest

yarn add @reduxjs/toolkit@latest

Changelog

RTK Query

RTK Query SSR and Rehydration Support

RTK Query now has support for SSR scenarios, such as the getStaticProps/getServerSideProps APIs in Next.js. Queries can be executed on the server using the existing dispatch(someEndpoint.initiate()) thunks, and then collected using the new await Promise.all(api.getRunningOperationPromises()) method.

API definitions can then provide an extractRehydrationInfo method that looks for a specific action type containing the fetched data, and return the data to initialize the API cache section of the store state.

The related api.util.getRunningOperationPromise() API adds a building block that may enable future support for React Suspense as well, and we'd encourage users to experiment with this idea.

Sharing Mutation Results Across Components

Mutation hooks provide status of in-progress requests, but as originally designed that information was unique per-component - there was no way for another component to see that request status data. But, we had several requests to enable this use case.

useMutation hooks now support a fixedCacheKey option that will store the result status in a common location, so multiple components can read the request status if needed.

This does mean that the data cannot easily be cleaned up automatically, so the mutation status object now includes a reset() function that can be used to clear that data.

Data Loading Updates

Query results now include a currentData field, which contains the latest data cached from the server for the current query arg. Additionally, transformResponse now receives the query arg as a parameter. These can be used to add additional derivation logic in cases when a hooks query arg has changed to represent a different value and the existing data no longer conceptually makes sense to keep displaying.

Data Serialization and Base Query Improvements

RTK Query originally only did shallow checks for query arg fields to determine if values had changed. This caused issues with infinite loops depending on user input.

The query hooks now use a "serialized stable value" hook internally to do more consistent comparisons of query args and eliminate those problems.

Also, fetchBaseQuery now supports a paramsSerializer option that allows customization of query string generation from the provided arguments, which enables better interaction with some backend APIs.

The BaseQueryApi and prepareheaders args now include fields for endpoint name, type to indicate if it's a query or mutation, and forced to indicate a re-fetch even if there was already a cache entry. These can be used to help determine headers like Cache-Control: no-cache.

Other RTK Query Improvements

API objects now have a selectInvalidatedBy function that accepts a root state object and an array of query tag objects, and returns a list of details on endpoints that would be invalidated. This can be used to help implement optimistic updates of paginated lists.

Fixed an issue serializing a query arg of undefined. Related, an empty JSON body now is stored as null instead of undefined.

There are now dev warnings for potential mistakes in endpoint setup, like a query function that does not return a data field.

Lazy query trigger promises can now be unwrapped similar to mutations.

Fixed a type error that led the endpoint return type to be erroneously used as a state key, which caused generated selectors to have an inferred state: never argument.

Fixed transformResponse to correctly receive the originalArgs as its third parameter.

api.util.resetApiState will now clear out cached values in useQuery hooks.

The RetryOptions interface is now exported, which resolves a TS build error when using the hooks with TS declarations.

RTK Core

createSlice Lazy Reducers and Circular Dependencies

For the last couple years we've specifically recommended using a "feature folder" structure with a single "slice" file of logic per feature, and createSlice makes that pattern really easy - no need to have separate folders and files for /actions and /constants any more.

The one downside to the "slice file" pattern is in cases when slice A needs to import actions from slice B to respond to them, and slice B also needs to listen to slice A. This circular import then causes runtime errors, because one of the modules will not have finished initializing by the time the other executes the module body. That causes the exports to be undefined, and createSlice throws an error because you can't pass undefined to builder.addCase() in extraReducers. (Or, worse, there's no obvious error and things break later.)

There are well-known patterns for breaking circular dependencies, typically requiring extracting shared logic into a separate file. For RTK, this usually means calling createAction separately, and importing those action creators into both slices.

While this is a rarer problem, it's one that can happen in real usage, and it's also been a semi-frequently listed concern from users who didn't want to use RTK.

We've updated createSlice to now lazily create its reducer function the first time you try to call it. That delay in instantiation should eliminate circular dependencies as a runtime error in createSlice.

createAsyncThunk Improvements

The condition option may now be async, which enables scenarios like checking if an existing operation is running and resolving the promise when the other instance is done.

If an idGenerator function is provided, it will now be given the thunkArg value as a parameter, which enables generating custom IDs based on the request data.

The createAsyncThunk types were updated to correctly handle type inference when using rejectWithValue().

Other RTK Improvements

createSlice and createReducer now accept a "lazy state initializer" function as the initialState argument. If provided, the initializer will be called to produce a new initial state value any time the reducer is given undefined as its state argument. This can be useful for cases like reading from localStorage, as well as testing.

The isPlainObject util has been updated to match the implementation in other Redux libs.

The UMD builds of RTK Query now attach as window.RTKQ instead of overwriting window.RTK.

Fixed an issue with sourcemap loading due to an incorrect filename replacement.

Dependency Updates

We've updated our deps to the latest versions:

We've also lowered RTK's peer dependency on React from ^16.14 to ^16.9, as we just need hooks to be available.

Other Redux Development Work

The Redux team has also been working on several other updates to the Redux family of libraries.

React-Redux v8.0 Beta

We've rewritten React-Redux to add compatibility with the upcoming React 18 release and converted its codebase to TypeScript. It still supports React 16.8+/17 via a /compat entry point. We'd appreciate further testing from the community so we can confirm it works as expected in real apps before final release. For details on the changes, see:

RTK "Action Listener Middleware" Alpha

We have been working on a new "action listener middleware" that we hope to release in an upcoming version of RTK. It's designed to let users write code that runs in response to dispatched actions and state changes, including simple callbacks and moderately complex async workflows. The current design appears capable of handling many of the use cases that previously required use of the Redux-Saga or Redux-Observable middlewares, but with a smaller bundle size and simpler API.

The listener middleware is still in alpha, but we'd really appreciate more users testing it out and giving us additional feedback to help us finalize the API and make sure it covers the right use cases.

RTK Query CodeGen

The RTK Query OpenAPI codegen tool has been rewritten with new options and improved output.

What's Changed

Fix "isLoading briefly flips back to true" #1519
createAsyncThunk: Async condition
Add arg to transformResponse
Add currentData property to hook results.
Use useSerializedStableValue for value comparison
useLazyQuery: Added docs for preferCache option
Correctly handle console logs in tests
Add reset method to useMutation hook
Allow for "shared component results" using the useMutation hook
🐛 Fix bug with useMutation shared results
Pass the ThunkArg to the idGenerator function
Support a custom paramsSerializer on fetchBaseQuery
SSR & rehydration support, suspense foundations
Add endpoint, type and forced to BaseQueryApi and prepareHeaders
Split off signature without AsyncThunkConfig for better inference
Update createReducer to accept a lazy state init function
Add selectInvalidatedBy
Allow for circular references by building reducer lazily on first reducer call
Update deps for 1.7
fetchBaseQuery: Return nullon empty body for JSON. Add DevWarnings
Add unwrap to QueryActionCreatorResult and update LazyQueryTrigger
Only set originalArgs if they're not undefined
Treat null as a valid plain object prototype in isPlainObject() in order to sync the util across reduxjs/* repositories
Export RetryOptions interface from retry.ts
Api.util.resetApiState should reset useQuery hooks
Fix issue where the global RTK object got overwritten in the UMD files
Fix broken sourcemap output due to bad filename replacement
Override unwrap behavior for buildInitiateQuery, update tests
Fix incorrect RTKQ endpoint definition types for correct selector typings
Use originalArgs in transformResponse