RTK Query Sustainable Setup As Codebase Grows In Complexity

[agusterodin]

I am loving RTK query for how powerful it is. My code, however, is getting really heavy. I feel as if many people would get turned off to RTK query solely for how complicated and dense the code ends up looking. Unless I am missing something, it seems like the convenience of TypeScript comes at the cost of everything needing to be defined in single object.

It doesn't help that RTK Query feels like a fully fledged library itself and deserves its own separate documentation site. I am sure that the maintainers put A LOT of thought into this decision and have good reasons, especially since RTK query is internally built off of other parts of RTK. Regardless, the docs feel cluttered now.

I have no problems understanding what is going on in both the docs and my code but I could imagine people who are newer to JS/TS/React/Redux being completely overwhelmed. I mean this in the most constructive possible way. This is my gut reaction to everything I have experienced so far. I never had this overwhelmed feeling when using other parts of RTK (like createSlice).

I have been experimenting with splitting the endpoints up into separate files like this. The plan is to have one file per corresponding controller in the backend. This is my initial attempt:

api/index.ts

import { EndpointBuilder } from '@reduxjs/toolkit/dist/query/endpointDefinitions'
import campaignEndpoints from './campaign'

const reducerPath = 'api' as const

const tagTypes = ['campaignMetrics'] as const

const baseQuery = fetchBaseQuery({
  baseUrl: '/',
  prepareHeaders: headers => {
    const accessToken = localStorage.getItem('access_token')
    if (accessToken) headers.set('authorization', `Bearer ${accessToken}`)
    return headers
  }
})

export const campaignsApi = createApi({
  reducerPath,
  baseQuery,
  tagTypes,
  endpoints: builder => ({
    ...campaignEndpoints(builder)
  }),
  refetchOnFocus: true,
  refetchOnReconnect: false
})

export type CampaignsApiEndpointBuilder = EndpointBuilder<typeof baseQuery, typeof tagTypes[number], typeof reducerPath>

api/campaign.ts

import { campaignsApi, CampaignsApiEndpointBuilder } from './index'

export default (builder: CampaignsApiEndpointBuilder) => {
  return {
    getCampaignMetricsById: builder.query<Metrics, number>({
      query: id => `campaign/${id}/metrics`,
      providesTags: ['campaignMetrics']
    }),
    getCampaignMetadataById: builder.query<CampaignMetadata, number>({
      query: id => `campaign/${id}`,
      providesTags: ['campaignMetrics']
    }),
    setCampaignActive: builder.mutation<void, { id: number; active: boolean }>({
      query: ({ id, active }) => ({
        url: `campaign/activate/${id}`,
        method: RequestMethod.Put,
        body: { active }
      }),
      invalidatesTags: ['campaignMetrics'],
      async onQueryStarted({ id, active }, { dispatch, queryFulfilled }) {
        const patchResult = dispatch(
          campaignsApi.util.updateQueryData('getCampaignMetadataById', id, draft => {
            Object.assign(draft, { active })
          })
        )
        try {
          await queryFulfilled
        }
        catch {
          patchResult.undo()
        }
      }
    })
  }
}

export const { useGetCampaignMetadataByIdQuery, useGetCampaignMetricsByIdQuery, useSetCampaignActiveMutation } = campaignsApi

TS inference stuff works perfectly. Unfortunately cyclical dependencies bite me in the ass and the app crashes when I run it. The console says Object(...) is not a function since campaignEndpoints is not defined when createApi gets executed.

I'm sure there are ways to restructure this to avoid circular dependencies. Does anyone have suggestions on a nice structure?

Also if there is an elegant way to structure things to accommodate a growing codebase it may be worth adding as an example in the docs.

[markerikson]

My first quick thought is that you should be using the patterns shown in the "Code Splitting" page to split up the endpoint definitions, even if you're not actually trying to literally code-split:

https://redux-toolkit.js.org/rtk-query/usage/code-splitting

[markerikson]

We don't have much specific guidance on file structure beyond "use feature folders, and put logic for a given feature into a single slice file":

https://redux.js.org/style-guide/style-guide#structure-files-as-feature-folders-with-single-file-logic

We also specifically recommend having a single API slice definition per app unless you truly have multiple completely different servers the app is talking to. However, the implementation of that API slice can be split across multiple files via injectEndpoints.

As to where you put those split implementations, that's totally up to you.

[agusterodin]

My personal rule of thumb is each controller on our backend has a corresponding api slice (each in it's own dedicated file). We put these in a folder called "api" in the root of our project. Here is an example how I structured an API for a personal project of mine:

api.zip

All other Redux stuff (slices, selectors, store initialization, etc) goes in a folder called "state" in the root of my project.

This is highly subjective, so find what works best for your project :D

[rozendale]

As a beginner in REACT, REDUX, TS and even JS, it is indeed overwhelming. However, I start to get along and RTK query seems to me amazing, hopefully it won't change.

[zzzbra]

One point that it might be helpful to emphasize in the docs, although it is said already in so many words, is that using RTKQ will not result in the data it cache's being stored in the same type of global state tree that older users of Redux probably think of first when they think of the library. Of course, one can put it there manually but then that would undermine the entire rationale behind creating RTKQ in the first place.

[Jonesus]

Any suggestions on other ways to organize this info?

I had similar difficulties finding the "Code Splitting" part of the documentation initially as well, as "code splitting" in my head maps more to bundle size optimization (which is exactly what you start the docs page with), but almost equally as important IMO is th easpect of organizing a project's codebase. Maybe the title could be changed to something like "Code Splitting & Organization", "Code Splitting & Project Structure", or have another page that highlights the injectEndpoints's capability of being used as a codebase organization feature in addition to bundle splitting?

[Chococrok]

Hello, I really like @agusterodin structure. The problem is that the utilities are only available on the api slice and not on the builder.

An other thing that is annoying is that injectEndpoints does not modify the api slice in place so I end up doing something like:

const withSomeEndpoints = addSomeEndpoints(baseApi);
const withOtherEndpoints = addOtherEndpoints(withSomeEndpoints);
...
export const fullApi = addAgainOtherEndpoints(withOtherEndpoints );
export {...} = fullApi;
...

But maybe I missed something ?

[phryneas]

It modifes everything in place, there is just no way the types can reflect that, especially not across file boundaries. There is no real value in building a fullApi at any place. Just inject into the empty api in all your files and export what you need from the file that injected.