export const api = createApi({ reducerPath: 'api', baseQuery: fetchBaseQuery({ baseUrl: '/api/' }), tagTypes: ['Post'], endpoints: (build) => ({ getPosts: build.query<Post[], void>({ query: () => 'posts', providesTags: (result) => result ? [...result.map(({ id }) => ({ type: 'Post' as const, id })), 'Post'] : ['Post'], }), addPost: build.mutation<Post, Pick<Post, 'title'>>({ query: (body) => ({ url: 'posts', method: 'POST', body, }), invalidatesTags: ['Post'], }), }), })

export const { useGetPostsQuery, useAddPostMutation } = api

// file: src/app/store.ts import { configureStore } from '@reduxjs/toolkit' import { api } from '../services/api'

export const store = configureStore({ reducer: { [api.reducerPath]: api.reducer, }, middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(api.middleware), })

// file: src/App.tsx import { Provider } from 'react-redux' import { store } from './app/store' import { useAddPostMutation, useGetPostsQuery } from './services/api'

function Posts() { const { data: posts = [] } = useGetPostsQuery() const [addPost] = useAddPostMutation()

return ( <button onClick={() => addPost({ title: 'Write docs' })}>Add {posts.map((post) => ( {post.title} ))} ) }

export function App() { return ( ) }


## Core Patterns

### Keep one API slice per base URL and extend it

```ts
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

export const api = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({ baseUrl: '/api/' }),
  endpoints: () => ({}),
})

export const postsApi = api.injectEndpoints({
  endpoints: (build) => ({
    getPosts: build.query<{ id: string; title: string }[], void>({
      query: () => 'posts',
    }),
  }),
})

Split files with injectEndpoints, not by making multiple createApi roots for the same backend.

Use tags for cache invalidation

type Post = { id: string; title: string }

export const api = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({ baseUrl: '/api/' }),
  tagTypes: ['Post'],
  endpoints: (build) => ({
    getPosts: build.query<Post[], void>({
      query: () => 'posts',
      providesTags: (result) =>
        result
          ? [...result.map(({ id }) => ({ type: 'Post' as const, id })), 'Post']
          : ['Post'],
    }),
    updatePost: build.mutation<Post, Pick<Post, 'id' | 'title'>>({
      query: ({ id, title }) => ({
        url: `posts/${id}`,
        method: 'PATCH',
        body: { title },
      }),
      invalidatesTags: (_result, _error, { id }) => [{ type: 'Post', id }],
    }),
  }),
})

Treat tags as the normal invalidation path before reaching for manual cache patching.

Do optimistic updates in endpoint lifecycles

type Post = { id: string; title: string }

export const api = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({ baseUrl: '/api/' }),
  tagTypes: ['Post'],
  endpoints: (build) => ({
    getPosts: build.query<Post[], void>({
      query: () => 'posts',
      providesTags: ['Post'],
    }),
    updatePostTitle: build.mutation<Post, Pick<Post, 'id' | 'title'>>({
      query: ({ id, title }) => ({
        url: `posts/${id}`,
        method: 'PATCH',
        body: { title },
      }),
      async onQueryStarted({ id, title }, { dispatch, queryFulfilled }) {
        const patch = dispatch(
          api.util.updateQueryData('getPosts', undefined, (draft) => {
            const post = draft.find((item) => item.id === id)
            if (post) {
              post.title = title
            }
          }),
        )

        try {
          await queryFulfilled
        } catch {
          patch.undo()
        }
      },
    }),
  }),
})

Keep optimistic and pessimistic cache updates inside endpoint lifecycle handlers so they stay coupled to the request.

Common Mistakes

CRITICAL Creating multiple API slices for one backend

Wrong:

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

type User = { id: string; name: string }

const baseQuery = fetchBaseQuery({ baseUrl: '/api/' })

const postsApi = createApi({
  reducerPath: 'api',
  baseQuery,
  endpoints: () => ({}),
})

const usersApi = createApi({
  reducerPath: 'api',
  baseQuery,
  endpoints: () => ({}),
})

Correct:

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

type User = { id: string; name: string }

const baseQuery = fetchBaseQuery({ baseUrl: '/api/' })

const api = createApi({
  reducerPath: 'api',
  baseQuery,
  endpoints: () => ({}),
})

const usersApi = api.injectEndpoints({
  endpoints: (build) => ({
    getUsers: build.query<User[], void>({ query: () => 'users' }),
  }),
})

One API slice per base URL preserves invalidation behavior and avoids duplicated middleware work.

Source: reduxjs/redux-toolkit:docs/rtk-query/api/createApi.mdx

HIGH Forgetting `api.reducer` or `api.middleware`

Wrong:

import { configureStore } from '@reduxjs/toolkit'

const store = configureStore({
  reducer: {},
})

Correct:

import { configureStore } from '@reduxjs/toolkit'

const store = configureStore({
  reducer: {
    [api.reducerPath]: api.reducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(api.middleware),
})

RTK Query hooks need both the reducer and middleware to manage cache state and request lifecycles.

Source: reduxjs/redux-toolkit:docs/tutorials/rtk-query.mdx

MEDIUM Persisting browser API cache by default

Wrong:

const storage = window.localStorage

const persistConfig = {
  key: 'root',
  storage,
}

Correct:

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

const api = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({ baseUrl: '/api/' }),
  endpoints: () => ({}),
})

Persisting RTK Query cache in browsers often keeps stale data around longer than users expect; treat persistence as a special case, not the default.

Source: reduxjs/redux-toolkit:docs/rtk-query/usage/persistence-and-rehydration.mdx

HIGH Patching cache from components

Wrong:

import { useEffect } from 'react'
import { useAppDispatch } from '../../app/hooks'

const dispatch = useAppDispatch()

useEffect(() => {
  dispatch(
    api.util.updateQueryData('getPosts', undefined, (draft) => {
      draft.push({ id: 'p3', title: 'Patched from component' })
    }),
  )
}, [dispatch])

Correct:

updatePostTitle: build.mutation<Post, Pick<Post, 'id' | 'title'>>({
  query: ({ id, title }) => ({
    url: `posts/${id}`,
    method: 'PATCH',
    body: { title },
  }),
  async onQueryStarted({ id, title }, { dispatch, queryFulfilled }) {
    const patch = dispatch(
      api.util.updateQueryData('getPosts', undefined, (draft) => {
        const post = draft.find((item) => item.id === id)
        if (post) {
          post.title = title
        }
      }),
    )

    try {
      await queryFulfilled
    } catch {
      patch.undo()
    }
  },
})

Component-level cache patches drift away from the mutation lifecycle that should own them.

Source: reduxjs/redux-toolkit:docs/rtk-query/usage/manual-cache-updates.mdx

HIGH Expecting invalidation to refetch unsubscribed queries

Wrong:

import { api } from './api'
import { store } from './store'

const subscription = store.dispatch(api.endpoints.getPosts.initiate())
subscription.unsubscribe()
store.dispatch(api.util.invalidateTags(['Post']))

Correct:

import { api } from './api'
import { store } from './store'

store.dispatch(api.endpoints.getPosts.initiate())
store.dispatch(api.util.invalidateTags(['Post']))

Invalidation only refetches actively subscribed queries; if no component is using that cache entry, RTK Query drops it and fetches again next time it is needed.

Source: reduxjs/redux-toolkit:docs/rtk-query/usage/automated-refetching.mdx

References

Endpoint lifecycle details and cache tradeoffs

Use tags for cache invalidation

Do optimistic updates in endpoint lifecycles

Common Mistakes

CRITICAL Creating multiple API slices for one backend

HIGH Forgetting api.reducer or api.middleware

MEDIUM Persisting browser API cache by default

HIGH Patching cache from components

HIGH Expecting invalidation to refetch unsubscribed queries

References

HIGH Forgetting `api.reducer` or `api.middleware`

manage-server-data/adopt-rtk-query

Adopt RTK Query

Setup