RTK 3.0 breaking changes: feedback wanted

[markerikson]

The 2.x and 3.0 roadmap lists the breaking changes we're planning for RTK 3.0. Most of them are still at the design stage. Tell us what would hurt, what you'd like to see, and what we've missed.

These are the main changes we'd like opinions on:

Endpoint definitions: query → request, and build.query.fn()

Reference:

• Add request: and build.query.fn() endpoint definitions #5521

We plan to rename the query field in endpoint definitions to request, and to move queryFn endpoints into a separate build.query.fn() call. Are you for or against either change? How many endpoints would you have to change, and would a codemod cover them?

Replacing the createApi module system

Reference:

• Add reactify and build the React createApi on the core API #5519
• Replace the module system with an extension interface #5520

The current module system is going away. In its place, a core API instance will get React support added at runtime, similar to injectEndpoints().

• Do you call buildCreateApi with custom modules? What for: custom hooks, a custom React context, unstable_sideEffectsInRender, or a module of your own?
• Do you use unstable_sideEffectsInRender? We expect to remove it.
• Would you use RTKQ in an environment without hooks (RSC, a non-React UI, plain Node), if it were easier to set up?

extraReducers → respondTo

• Reference: Add respondTo as an alias for extraReducers, replacing it in 3.0 #5526

respondTo arrives as an alias in 2.17, and extraReducers is removed in 3.0. Any objections to the name or to the timing?

createSlice customization and creators

We're revamping how createSlice is customized, so you can add your own reducer "creators" (for example, an entity adapter creator) and so the async thunk support doesn't get bundled when you don't use it. We have an earlier draft of the concept that will be revamped for integration into 3.0:

• Allow providing custom slice creators when calling createSlice #4348

Do you use buildCreateSlice or asyncThunkCreator today? What creators would you write?

Swappable immutability library

Reference:

• Add an immutability option to buildCreateSlice and createApi #5527

Immer stays the default, but you'd be able to swap in another equivalent immutability library behind a standard interface. Would you use this? Which alternate library would you use (or a no-op setup and handwritten reducers), and why?

Packaging and support floors

Reference:

• Switch to ESM-only packaging #5529

RTK 3.0 will be shipping ESM-only and requiring TS 6.0 or newer. We also plan on moving the redux-thunk package directly into the redux core.

• Does either packaging change block you? Tell us which tools are involved (bundler, test runner, Node version, React Native / Metro, Jest).
• Do you still have code that imports from redux-thunk directly?

Anything else

What pain points should 3.0 fix that aren't on the roadmap? What do you need from the upgrade path: codemods, lint rules, a migration guide, deprecation warnings in 2.x? What problems did you run into upgrading from 1.x to 2.x?

Questions about current RTK Query behavior (cache access, initiate() promises, invalidation timing, SSR and hydration) go in the RTK Query usage discussion

[wirdehall]

Most of it either looks good or doesn't really affect our projects that much.
My biggest concern is for the change regarding Replacing the createApi module system

One of our applications use buildCreateApi, and more importantly unstable__sideEffectsInRender.
We have implemented SSR by our own using react's api's. To prevent the server from sending half finished pages due to waiting for data fetching from the api we suspend while queries are loading.

I saw you mentioned suspense hooks in issue 5519 but I'm not sure on how this would workout in practise.

Here's some code that we use today so you know how we use it.

Small wrapper for handling suspense:

import type { TypedUseQueryHookResult, BaseQueryFn } from '@reduxjs/toolkit/query/react';
import type { ThunkAction, UnknownAction } from '@reduxjs/toolkit';

import { useAppDispatch } from '@data/hooks';

type SsrThunkAction = ThunkAction<Promise<unknown> | undefined, unknown, unknown, UnknownAction>;

type SsrSuspenseApi = {
  reducerPath: string;
  endpoints: Record<string, unknown>;
  util: {
    getRunningQueryThunk(endpointName: string, args: unknown): SsrThunkAction;
  };
};

export function useWithSsrSuspense<T extends TypedUseQueryHookResult<unknown, unknown, BaseQueryFn>>(
  result: T,
  api: SsrSuspenseApi,
): T & { ssrPromise: Promise<unknown> | null } {
  const dispatch = useAppDispatch();

  if(result.endpointName !== undefined && api.endpoints[result.endpointName] === undefined) {
    throw new Error(`Error: useWithSsrSuspense is provided the wrong api, endpoint ${result.endpointName} does not exist on ${api.reducerPath}`);
  }

  const ssrPromise = (import.meta.env.SSR && result.isLoading && !result.error && result.requestId !== undefined && result.endpointName !== undefined)
    ? dispatch(api.util.getRunningQueryThunk(result.endpointName, result.originalArgs)) ?? null
    : null;

  return { ...result, ssrPromise };
}


export function useSsrSuspend(...promises: (Promise<unknown> | null)[]): void {
  const pending = promises.filter((p): p is Promise<unknown> => p !== null);
  if (pending.length > 0) {
    throw Promise.all(pending);
  }
}

Example of usage in a react componet:

  const {
    data: productTypeData,
    isLoading: productTypeIsLoading,
    isError: productTypeIsError,
    ssrPromise: p1
  } = useWithSsrSuspense(productTypeApi.useGetByUrlSlugQuery(urlSlug), productTypeApi);
  const {
    data: productsData,
    isLoading: productsIsLoading,
    isError: productsIsError,
    ssrPromise: p2,
    refetch: refetchProducts,
  } = useWithSsrSuspense(productApi.useGetByTypeIdQuery(productTypeData?.productType.id ?? 0, { skip: productTypeData === undefined}), productApi);
  useSsrSuspend(p1, p2);

And we create our api like so:

const createApi = buildCreateApi(coreModule(), reactHooksModule({ unstable__sideEffectsInRender: import.meta.env.SSR }));

Basically as long as we are on the server I.E. import.meta.env.SSR is set to true, we will suspend the rendering untill all requests are done so ReactDOM.renderToPipeableStream doesn't start sending unfinished pages.

On client side it will just behave like regular react and RTK Query and we won't suspend while waiting.

As long as there is a reasonable solution for this kind of thing going forward it should be fine.
One thing that is important is too be able to call multiple requests, then suspend untill all of them are done so we don't get a waterfall wait scenario.

In regard to the other changes I don't see any problem with any of them, and most of them seams reasonable. If you like I could give you more detailed feedback on them as well but I don't think it would provide much value for you.

And as always, thanks for your great work!