v1.9.0

[markerikson]

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:

• getRunningQueryThunk(endpointName, queryArgs)
• getRunningMutationThunk(endpointName, fixedCacheKeyOrRequestId)
• getRunningQueriesThunk()
• 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 TS 4.8.

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 by @msutkowski in Add isJsonContentType predicate to fetchBaseQuery #2331
• Add jsonContentType to fetchBaseQuery options by @msutkowski in Add jsonContentType to fetchBaseQuery options #2403
• Add ThunkMiddleware to the re-exported types from redux-thunk by @orta in Add ThunkMiddleware to the re-exported types from redux-thunk #2451
• add timeout option to fetchBaseQuery by @phryneas in add timeout option to fetchBaseQuery #2143
• createSlice: use template literal types for action type by @phryneas in createSlice: use template literal types for action type #2250
• add types for manually typing hook results in userland code by @phryneas in add types for manually typing hook results in userland code #2276
• Add 'content-type' ResponseHandler by @taylorkline in Add 'content-type' ResponseHandler #2363
• feature : endpoint-specific args serializers by @michal-kurz in feature : endpoint-specific args serializers #2493
• RFC: add "merge" functionality by @phryneas in RFC: add "merge" functionality #1059
• Add runtime deprecation warning for reducer object notation by @markerikson in Add runtime deprecation warning for reducer object notation #2591
• feat: Add the ability to type StoreEnhancers by @fostyfost in feat: Add the ability to type StoreEnhancers #2550
• Batch RTKQ "subscribe on reject" actions, and improve cache collection timer handling by @markerikson in Batch RTKQ "subscribe on reject" actions, and improve cache collection timer handling #2599
• add transformErrorReponse to rtkq endpoints by @dreyks in add transformErrorReponse to rtkq endpoints #1841
• Fix manually initiate()d rtk-query promises by @wesen in Fix manually initiate()d rtk-query promises #2187
• Implement codemods for createReducer and createSlice builder by @markerikson in Implement codemods for createReducer and createSlice builder #2602
• RFC: Expose endpoint types by @phryneas in RFC: Expose endpoint types #1646
• add createAsyncThunk.withTypes by @phryneas in add createAsyncThunk.withTypes #2604
• return promise from query result & hook refetch by @phryneas in return promise from query result & hook refetch #2212
• retry condition by http error response by @kahirokunn in retry condition by http error response #2239
• implemented upsertQueryData functionality per Add upsertQueryData functionality #1720 Add upsertQueryData functionality per issue #1720 #2007 by @barnabasJ in implemented upsertQueryData functionality per #1720 #2007 #2266
• Consolidate RTKQ middleware to simplify stack size by @markerikson in Consolidate RTKQ middleware to simplify stack size #2641
• Try fixing createAsyncThunk issues with TS 4.8 by @markerikson in Try fixing createAsyncThunk issues with TS 4.8 #2643
• Fix assorted issues with the RTKQ middleware refactor by @markerikson in Fix assorted issues with the RTKQ middleware refactor #2644
• fix upsertQueryData race situations by @phryneas in fix upsertQueryData race situations #2646
• Fix upsert by @phryneas in Fix upsert #2669
• Export the BaseQueryApi interface from rtk-query so it can be used as a type in TypeScript without importing from dist/. by @nsthorat in Export the BaseQueryApi interface from rtk-query so it can be used as a type in TypeScript without importing from dist/. #2740
• Fix retryCondition error. by @phryneas in Fix retryCondition error. #2743
• fix: export ToolkitStore interface from configureStore by @adamhari in fix: export ToolkitStore interface from configureStore #2750
• reset dispatchQueued variable after flushing by @phryneas in reset dispatchQueued variable after flushing #2757
• Add forceRefetch to QueryExtraOptions by @schadenn in Add forceRefetch to QueryExtraOptions #2663
• Speed up subscription behavior by tracking state in middleware by @markerikson in Speed up subscription behavior by tracking state in middleware #2759
• prepareHeaders does not need to return headers any more by @phryneas in prepareHeaders does not need to return headers any more #2775
• Add codemods-cli and rewrite "object reducer" codemods by @markerikson in Add codemods-cli and rewrite "object reducer" codemods #2768
• remove alpha compatibility fallbacks by @phryneas in remove alpha compatibility fallbacks #2777
• fix skipToken behaviour in useQueryState by @phryneas in fix skipToken behaviour in useQueryState #2779
• fetchBaseQuery: allow headers option by @phryneas in fetchBaseQuery: allow headers option #2778
• [breaking fix] replace getRunningOperationPromise(s) with getRunning(Query|Queries|Mutation|Mutations)Thunk by @phryneas in [breaking fix] replace getRunningOperationPromise(s) with getRunning(Query|Queries|Mutation|Mutations)Thunk #2481
• General pre-1.9-beta cleanup by @markerikson in General pre-1.9-beta cleanup #2789
• Convert "middleware not registered" warning into a full error by @markerikson in Convert "middleware not registered" warning into a full error #2792
• Rework endpoint serializeQueryArgs to allow object/number returns by @markerikson in Rework endpoint serializeQueryArgs to allow object/number returns #2835
• allow for global responseHandler and validateStatus configuration by @phryneas in allow for global responseHandler and validateStatus configuration #2823
• Fix refetches when sQA returns same value and queryArgs are object by @markerikson in Fix refetches when sQA returns same value and queryArgs are object #2844
• Add an auto-batching enhancer that delays low-pri notifications and use with RTKQ by @markerikson in Add an auto-batching enhancer that delays low-pri notifications and use with RTKQ #2846
• Check middleware registration directly to avoid persistence issues by @markerikson in Check middleware registration directly to avoid persistence issues #2850
• Fix "running thunks" types and remove unnecessary RTKQ selectors by @markerikson in Fix "running thunks" types and remove unnecessary RTKQ selectors #2856
• Make autobatching notification queueing configurable by @markerikson in Make autobatching notification queueing configurable #2857
• Hopefully final v1.9 tweaks by @markerikson in Hopefully final v1.9 tweaks #2859

Full Changelog: v1.8.6...v1.9.0

---

This discussion was created from the release v1.9.0.

[piotrlubecki]

It looks like this PR: #2779, has broken skip token logic for me. I was modifying one of the query props after the response from backend was received. In this particular case it was very useful not to trigger next request, because one of the parameters is an array and I was creating new reference each time. I am aware that in this case I can fetch data manually, but using skip was easier and worked really nice (before 1.9.0).

When calling useQueryState(skipToken) returning previous data allowed me to manually specify when we wanted to make new request. I thought that it was a feature, not a bug.

Currently returning undefined is breaking logic and forces refactor. Maybe it will be possible to introduce flag allowing to decide if previous data or undefined should be returned? If not maybe it could be added to breaking changes, as probably some other developers might found this behavior useful and might miss that it has been changed?

Simplified example of what I was doing:

Component:

export default function Cart() {
  const items = useAppSelector((state) => state.cart.items);
  const currency = useAppSelector((state) => state.userSettings.currency);
  const addedCouponCode = useAppSelector((state) => state.cart.addedCouponCode);
  const couponCodes = useAppSelector((state) => state.cart.couponCodes);
  const skipQuery = useAppSelector((state) => state.cart.skipQuery);
  const dispatch = useAppDispatch();
  const router = useRouter();
  const language = removeHypen(router.locale ?? 'EnUk');

  const { data, error, isLoading, isUninitialized } = useGetOrderSummaryQuery(
    {
      language,
      items,
      currency,
      couponCodes,
      addedCouponCode,
    },
    { skip: !currency || skipQuery }
  );

  useEffect(() => {
    if (!data) {
      return;
    }

    const products = data.items.map((x) => {
      return { variantReferenceId: x.variantReferenceId, quantity: x.quantity };
    });

    dispatch(setCartQuantity(products));

// dispach below is setting skipQuery  to true
    dispatch(setCouponCodes(data.coupons));
  }, [data]);

  if ((isLoading || isUninitialized) && !skipQuery) {
    return <CartSkeleton />;
  }

  if (error) {
    return <div>error...</div>;
  }

  if (!data) {
// In 1.9.0 I am getting this page even if backend has returned data successfully
    return <EmptyCart />;
  }

  return (
// Before 1.9.0 I am getting this page if backend has returned data successfully
      <NotEmptyCart />
  );
}

Reducer:

export const cartSlice = createSlice({
  name: 'cart',
  initialState,
  reducers: {
    setCartQuantity: (state, action: PayloadAction<ShoppingCartProduct[]>) => {
      state.skipQuery = false;
      state.items = action.payload;
      setProductQuantityInLocalStorage(action.payload);
    },
    setCouponCodes: (state, action: PayloadAction<CuponCode[]>) => {

// here I manually prevent next fetch of data
      state.skipQuery = true;
      state.couponCodes = action.payload;
      delete state.addedCouponCode;
      setCouponsInLocalStorage(action.payload);
    },
  },
  extraReducers: (builder) => {
    builder
      .addCase(setLanguage, (state) => {
        state.skipQuery = false;
      })
      .addCase(setCurrency, (state) => {
        state.skipQuery = false;
      })
      .addCase(setUserSettings, (state) => {
        state.skipQuery = false;
      });
  },
});

[markerikson]

@piotrlubecki : filed #2871 to discuss this - thoughts there?

[kasparkallas]

🥳 Wow, I appreciate the continued effort by you guys! You truly make redux a great and powerful tool to use!

[ivan-jelev]

Great work! Highly appreciate your effort 🙇
It's such a relief to remove all our custom crap which makes Infinite scroll possible

[SpaceCowboy326]

Very exciting, thank you for all your effort! I believe one of the headers has a typo:
"forceRefresh option", everywhere else refers to "forceRefetch".

[AnimeAllstar]

Is there a way to hide the deprecation warning for createSlice.extraReducers?

[markerikson]

@AnimeAllstar : yes, stop using the "object" syntax and switch to the "builder" syntax, as shown in the release notes :)