| name | manage-server-data/adopt-rtk-query |
| description | Use this when adding RTK Query as the default server-data and document-cache layer. Covers createApi, store integration, hooks, invalidation behavior, optimistic updates, and deciding when RTK Query is the right cache model.
|
| type | lifecycle |
| library | @reduxjs/toolkit |
| library_version | 2.11.2 |
| requires | ["build-modern-redux-apps/modern-redux"] |
| sources | ["reduxjs/redux-toolkit:docs/rtk-query/api/createApi.mdx","reduxjs/redux-toolkit:docs/rtk-query/usage/automated-refetching.mdx","reduxjs/redux-toolkit:docs/rtk-query/usage/manual-cache-updates.mdx","reduxjs/redux-toolkit:docs/rtk-query/usage/persistence-and-rehydration.mdx","reduxjs/redux-toolkit:docs/tutorials/rtk-query.mdx","reduxjs/redux:docs/style-guide/style-guide.md"] |
Adopt RTK Query
Setup
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
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'],
}),
addPost: build.mutation<Post, Pick<Post, 'title'>>({
query: (body) => ({
url: ,
: ,
body,
}),
: [],
}),
}),
})
{ useGetPostsQuery, useAddPostMutation } = api
{ configureStore }
{ api }
store = ({
: {
[api.]: api.,
},
:
().(api.),
})
{ }
{ store }
{ useAddPostMutation, useGetPostsQuery }
() {
{ : posts = [] } = ()
[addPost] = ()
(
)
}
() {
(
)
}
Core Patterns
Keep one API slice per base URL and extend it
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',
: { title },
}),
: [{ : , 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', , {
post = draft.( item. === id)
(post) {
post. = title
}
}),
)
{
queryFulfilled
} {
patch.()
}
},
}),
}),
})
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
