React Navigation Redux Integration Helpers
raw JSON →This package provides utilities and middleware to integrate React Navigation's state management with Redux. It allows developers to store and manipulate navigation state directly within a Redux store, enabling use cases like custom navigation actions, advanced state persistence, and synchronized state validation between navigation and other application data. The current stable version is 4.0.1, primarily compatible with React Navigation v3 and v4. It does not actively support React Navigation v5 and newer, which moved to a different state management paradigm based on context and hooks. Release cadence has historically been tied to major and minor releases of React Navigation v3 and v4, with recent activity focused on maintenance and compatibility fixes for those older ecosystems. Key differentiators include direct Redux control over navigation state, enabling custom router logic via Redux actions/reducers, and granular control over state persistence, which are harder to achieve with default React Navigation containers.
Common errors
error TypeError: Cannot read properties of undefined (reading 'nav') ↓
createNavigationReducer(AppNavigator) output to the key specified in createReactNavigationReduxMiddleware((state) => state.YOUR_KEY). Ensure the Redux store is initialized before the navigator attempts to access its state. error Invariant Violation: The navigator's state is not managed by Redux. ↓
applyMiddleware(middleware) is included when creating your Redux store and that AppWithNavigationState (the connected component) is correctly receiving the navigation state via mapStateToProps. error Flow error: Cannot import '@react-navigation/core' or missing type definition for '@react-navigation/core'. ↓
@react-navigation/core Flow libdef (e.g., yarn add --dev flow-typed then flow-typed install @react-navigation/core@* or manually link the definition) and ensure it's referenced in your .flowconfig. error Type 'NavigationState' is not assignable to type 'Partial<Readonly<NavigationState>>' in TypeScript or Flow. ↓
react-navigation related packages (including react-navigation-redux-helpers) are using compatible versions. If using TypeScript, check for @types/react-navigation or @types/react-navigation-redux-helpers and their versions. You might need to cast types or update type definitions if they are outdated. Warnings
breaking This library is designed for React Navigation v3 and v4. It is not compatible with React Navigation v5 and newer, which introduced a complete architectural overhaul based on React Context and hooks, making this Redux integration pattern obsolete for newer versions. ↓
breaking Version 4.0.0 introduced the `ThemeContext` and explicitly broke compatibility with React Navigation 3.11 and earlier versions. Projects on older React Navigation 3 releases should not upgrade to `react-navigation-redux-helpers@4.0.0` or higher. ↓
gotcha For Flow users, versions 4.0.1 and 3.0.8 (and later maintenance releases in those lines) import directly from `@react-navigation/core`. This necessitates installing the `@react-navigation/core` libdef in your Flow setup, even if you primarily use `react-navigation` itself, potentially leading to Flow type errors if not handled. ↓
gotcha Changes related to `react-native-safe-area-context` imports and context exposure (introduced in 3.0.4) were problematic, leading to backing out of the dependency in 3.0.6 due to native linking requirements. This indicates potential instability or complex setup if trying to integrate with `react-native-safe-area-area-context` in older `react-navigation-redux-helpers` versions. ↓
Install
npm install react-navigation-redux-helpers yarn add react-navigation-redux-helpers pnpm add react-navigation-redux-helpers Imports
- createReduxContainer wrong
const createReduxContainer = require('react-navigation-redux-helpers').createReduxContainer;correctimport { createReduxContainer } from 'react-navigation-redux-helpers'; - createReactNavigationReduxMiddleware wrong
const createReactNavigationReduxMiddleware = require('react-navigation-redux-helpers').createReactNavigationReduxMiddleware;correctimport { createReactNavigationReduxMiddleware } from 'react-navigation-redux-helpers'; - createNavigationReducer wrong
const createNavigationReducer = require('react-navigation-redux-helpers').createNavigationReducer;correctimport { createNavigationReducer } from 'react-navigation-redux-helpers';
Quickstart
import { createStackNavigator } from 'react-navigation';
import { createStore, applyMiddleware, combineReducers } from 'redux';
import { createReduxContainer, createReactNavigationReduxMiddleware, createNavigationReducer } from 'react-navigation-redux-helpers';
import { Provider, connect } from 'react-redux';
import React from 'react';
import { View, Text, Button } from 'react-native';
// Define some dummy screens and a navigator
class HomeScreen extends React.Component {
render() {
return (
<View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
<Text>Home Screen</Text>
<Button
title="Go to Details"
onPress={() => this.props.navigation.navigate('Details')}
/>
</View>
);
}
}
class DetailsScreen extends React.Component {
render() {
return (
<View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
<Text>Details Screen</Text>
<Button
title="Go back"
onPress={() => this.props.navigation.goBack()}
/>
</View>
);
}
}
const AppRouteConfigs = {
Home: HomeScreen,
Details: DetailsScreen,
};
const AppNavigator = createStackNavigator(AppRouteConfigs);
const navReducer = createNavigationReducer(AppNavigator);
const appReducer = combineReducers({
nav: navReducer,
// Add other application reducers here if needed
});
const middleware = createReactNavigationReduxMiddleware(
state => state.nav,
);
const App = createReduxContainer(AppNavigator);
const mapStateToProps = (state) => ({
state: state.nav,
});
const AppWithNavigationState = connect(mapStateToProps)(App);
const store = createStore(
appReducer,
applyMiddleware(middleware),
);
class Root extends React.Component {
render() {
return (
<Provider store={store}>
<AppWithNavigationState />
</Provider>
);
}
}
export default Root;