React Navigation Redux Integration Helpers

raw JSON →
4.0.1 verified Thu Apr 23 auth: no javascript maintenance

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.

error TypeError: Cannot read properties of undefined (reading 'nav')
cause The `navStateSelector` function passed to `createReactNavigationReduxMiddleware` cannot find the navigation state within your Redux store, or the `navReducer` has not been properly assigned to the `nav` key (or whatever key is used) in your `combineReducers` setup.
fix
Verify that your Redux root reducer correctly assigns the 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.
cause This error typically indicates that `createReduxContainer` was used, but the Redux middleware (`createReactNavigationReduxMiddleware`) was not correctly applied to your Redux store, or the navigation state is not being correctly passed to the connected navigator component.
fix
Double-check that 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'.
cause You are likely using Flow and one of the affected versions of `react-navigation-redux-helpers` (e.g., 4.0.1, 3.0.8) which imports types from `@react-navigation/core`, but your Flow setup does not include the necessary libdef.
fix
Install the @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.
cause This is a common type mismatch when the version of `react-navigation` or `react-navigation-redux-helpers` types don't perfectly align, or when custom type definitions for navigation state are used without proper compatibility.
fix
Ensure all 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.
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.
fix For React Navigation v5+, use its built-in state management via context and hooks, or explore community solutions designed specifically for the v5+ architecture if Redux integration is still desired.
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.
fix If using React Navigation 3.11 or earlier, stick to `react-navigation-redux-helpers` versions below 4.0.0 (e.g., `^3.0.x`). Alternatively, upgrade your `react-navigation` dependency to 3.12 or 4.x.
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.
fix Ensure that the `@react-navigation/core` Flow libdef is correctly installed and configured in your project. This typically involves adding it to your `[libs]` section in `.flowconfig`.
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.
fix If encountering issues with `react-native-safe-area-context`, ensure you are on a version that explicitly supports it or avoid using `react-navigation-redux-helpers` versions in the problematic range, especially if your project doesn't handle native linking for that specific dependency.
npm install react-navigation-redux-helpers
yarn add react-navigation-redux-helpers
pnpm add react-navigation-redux-helpers

This example demonstrates how to set up a basic React Navigation stack navigator and integrate its state management with a Redux store using `react-navigation-redux-helpers`. It defines a simple app structure, creates a Redux store with the navigation reducer, applies the Redux middleware, and connects the navigator to the Redux state.

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;