Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
useRequest
✓ import { useRequest } from 'redux-query-react';
✗ const useRequest = require('redux-query-react').useRequest;
Primary hook for declaratively fetching data based on component lifecycle. The library primarily uses named exports.
useMutation
✓ import { useMutation } from 'redux-query-react';
✗ import useMutation from 'redux-query-react';
Primary hook for performing data mutations (e.g., POST, PUT, DELETE) with optional optimistic updates. This is a named export.
connectRequest
✓ import { connectRequest } from 'redux-query-react';
✗ const connectRequest = require('redux-query-react').connectRequest;
Higher-Order Component (HOC) for integrating data dependencies with class components or pre-hooks functional components. Ships with TypeScript types for HOCs and hooks.
This example demonstrates how to set up a Redux store with `redux-query`, define a `networkHandler` (mocked here), and use `redux-query-react`'s `useRequest` hook to fetch and display user data, along with `useMutation` for optimistic updates on a user's name.
import React from 'react';
import { createStore, combineReducers, applyMiddleware } from 'redux';
import { Provider } from 'react-redux';
import { queriesReducer, queriesMiddleware, QueryConfig } from 'redux-query';
import { useRequest, useMutation } from 'redux-query-react';
import { createNetworkHandler } from 'redux-query-interface-superagent'; // For a real app, install this
// A mock network handler for demonstration purposes
const mockNetworkHandler = createNetworkHandler({
adapter: (config) => {
console.log('Mock API call:', config.url, config.method, config.body);
return new Promise((resolve, reject) => {
setTimeout(() => {
if (config.url === '/api/users/1') {
resolve({
status: 200,
body: { id: 1, name: 'Alice', email: 'alice@example.com' },
headers: new Headers(),
});
} else if (config.url === '/api/users/1' && config.method === 'PUT') {
resolve({
status: 200,
body: { id: 1, name: config.body.name, email: 'alice@example.com' },
headers: new Headers(),
});
} else {
reject({ status: 404, body: 'Not Found', headers: new Headers() });
}
}, 500);
});
}
});
// Setup Redux store with redux-query
const rootReducer = combineReducers({
queries: queriesReducer,
// Add other reducers here
});
const store = createStore(
rootReducer,
applyMiddleware(queriesMiddleware(mockNetworkHandler))
);
interface User {
id: number;
name: string;
email: string;
}
// Define a query config for fetching a user
const getUserQuery: QueryConfig = {
url: '/api/users/1',
update: {
entities: (prevEntities: any = {}, newEntities: any) => ({
...prevEntities,
user: newEntities.user, // Assuming API returns { user: { ... } }
}),
},
// Map the query response data to a specific key, if needed.
// data: (queryState) => queryState.entities.user
};
const UserProfile: React.FC = () => {
// Use useRequest to fetch user data
const { isPending, isFinished, data } = useRequest<User>(getUserQuery);
// Use useMutation to update user data with optimistic updates
const [updateUserName, { isPending: isUpdatingName }] = useMutation(
(newName: string) => ({
url: '/api/users/1',
method: 'PUT',
body: { name: newName },
update: {
entities: (prevEntities: any = {}, newEntities: any) => ({
...prevEntities,
user: newEntities.user,
}),
},
optimistic: {
entities: (prevEntities: any = {}) => ({
...prevEntities,
user: { ...prevEntities.user, name: newName + ' (optimistic)' },
}),
},
})
);
const handleRenameUser = () => {
updateUserName('Bob');
};
if (isPending) return <div>Loading user profile...</div>;
if (!data) return <div>No user data available.</div>;
return (
<div>
<h2>User Profile</h2>
<p>ID: {data.id}</p>
<p>Name: {data.name} {isUpdatingName && '(Updating...)'}</p>
<p>Email: {data.email}</p>
<button onClick={handleRenameUser} disabled={isUpdatingName}>Rename to Bob</button>
</div>
);
};
const App: React.FC = () => (
<Provider store={store}>
<UserProfile />
</Provider>
);
export default App;
Debug
Known issues
breakingMajor architectural changes in `redux-query` v2 required significant upgrades. The `request` fields in the `queries` reducer and actions were replaced with `networkHandler`, and rollback behavior for mutations was updated. Users migrating from `1.x` to `2.x` must consult the v2 transition guide for `redux-query`.fixRefer to the `redux-query` v2 transition guide for detailed migration steps, focusing on `networkHandler` implementation and revised mutation configurations. This includes updates to how network requests are defined and how optimistic updates and rollbacks are handled.
affects: >=2.0.0
gotcha`redux-query-react` has specific peer dependency requirements, notably for `react-redux@7.1.0` and `redux-query@^3.0.0-alpha.10`. Mismatches with these versions can lead to runtime errors or unexpected behavior due to API changes in these core libraries.fixEnsure your project's `react-redux` and `redux-query` versions precisely match or are compatible with the peer dependency ranges specified in `redux-query-react`'s `package.json`. Use `npm install --legacy-peer-deps` or `yarn add --peer-deps-strict false` if you encounter peer dependency warnings and are confident in compatibility, but verify thoroughly.
affects: All versions
gotchaWhile `redux-query-react` gained support for Redux v4 in `v2.3.1`, upgrading Redux itself in your application may introduce other breaking changes or require adjustments in your Redux store configuration outside of `redux-query`.fixIf upgrading Redux to v4+, ensure `redux-query-react` is at least `v2.3.1`. Review Redux's official migration guides for any breaking changes related to `createStore`, middleware, or enhancers, in addition to `redux-query-react`'s specific updates.
affects: Prior to v2.3.1 if using Redux v4. From v2.3.1 onward, potential Redux-specific migration challenges.
breaking`redux-query` v2 introduced new, safer rollback behavior when mutations fail, along with a `rollback` option in query configs. Developers relying on optimistic updates in earlier versions might need to adjust their mutation logic to account for these changes.fixUpdate mutation configurations to leverage the new `rollback` option and review how optimistic updates interact with failure scenarios to ensure desired behavior. Consult the `redux-query` v2 transition guide for details on the new rollback mechanism.
affects: <2.0.0
Errors
Common errors & fixes
Error: Invariant Violation: Hooks can only be called inside of the body of a function component.
`useRequest` or `useMutation` is being called outside of a React functional component or a custom hook that adheres to React's rules of hooks.
fixEnsure `useRequest` and `useMutation` are only invoked directly within the top level of a functional component or a custom hook that follows React's rules for calling hooks.
Invariant Violation: Could not find `store` in the context of `<Connect(Component)>`
The `redux-query` middleware or reducer is not correctly integrated into your Redux store, or your React components are not wrapped within a `<Provider store={store}>` from `react-redux`.
fixVerify that `queriesReducer` is added to your root reducer and `queriesMiddleware` is applied to your Redux store. Ensure the top-level component that uses `redux-query-react` hooks or HOCs is rendered inside a `react-redux` `<Provider>` component.
Module not found: Error: Can't resolve 'redux-query-react' in '...'
The `redux-query-react` package is not installed in your project, or there is a typo in the import path.
fixRun `npm install redux-query-react` or `yarn add redux-query-react` to install the package. Double-check your import statements for any typos in the package name or path.
Audit
Dependencies
reactrequiredRequired for building user interfaces with React components and hooks.
react-reduxrequiredProvides the Provider component and hooks to connect React components to the Redux store.
redux-queryrequiredThe core library for network state management that redux-query-react integrates with.