react-navigation / redux-helpers

Redux middleware and utils for React Navigation
Other
295 stars 43 forks source link

react-navigation-redux-helpers

This package allows the user to manage their React Navigation state from within Redux.

DEPRECATED as of React Navigation 5

React Navigation no longer supports storing its state within Redux. You should be able to refactor your custom navigation logic into custom navigators, custom routers, and onStateChange callbacks.

How it works

  1. In React Navigation, "containers" wrap navigators, and own the state for that navigator and any nested navigators. This package implements a container that uses Redux as a backing store.
  2. A Redux middleware is used so that any events that mutate the navigation state properly trigger React Navigation's event listeners.
  3. Finally, a reducer enables React Navigation actions to mutate the Redux state.

Motivation

Most projects that are using both Redux and React Navigation don't need this library. Things like state persistence and BackHandler behavior aren't handled directly by createReduxContainer, but are handled by the default createAppContainer. However, there are some things this library makes easier:

  1. It's possible to implement custom actions, allowing you to manipulate the navigation state in ways that aren't possible with the stock React Navigation actions. Though it's possible to implement custom routers in React Navigation to do this, it's arguably cleaner via Redux. (If you want animations to run on your action, make sure to set isTransitioning to true!)
  2. This library allows the user to customize the persistence of their navigation state. For instance, you could choose to persist your navigation state in encrypted storage. Most users don't need this, as there are no practical downsides to handling persistence of navigation state and Redux state separately. Note that stock React Navigation supports some basic degree of persistence customization.
  3. You can implement custom reducer behavior to validate state and maintain consistency between navigation state and other application state. This is again possible with custom routers, but likely cleaner to implement without, especially in the context of an existing Redux setup.

Installation

  yarn add react-navigation-redux-helpers

or

  npm install --save react-navigation-redux-helpers

Example

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';

const AppNavigator = createStackNavigator(AppRouteConfigs);

const navReducer = createNavigationReducer(AppNavigator);
const appReducer = combineReducers({
  nav: navReducer,
  ...
});

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>
    );
  }
}

API

createReactNavigationReduxMiddleware (required)

function createReactNavigationReduxMiddleware<State: {}>(
  navStateSelector: (state: State) => NavigationState,
  key?: string,
): Middleware<State, *, *>;

createReduxContainer (required)

function createReduxContainer(
  navigator: Navigator,
  key?: string,
): React.ComponentType<{ state: NavigationState, dispatch: Dispatch }>;

createNavigationReducer (optional)

function createNavigationReducer(navigator: Navigator): Reducer<*, *>;

Miscellaneous

Mocking tests

To make Jest tests work with your React Navigation app, you need to change the Jest preset in your package.json:

"jest": {
  "preset": "react-native",
  "transformIgnorePatterns": [
    "node_modules/(?!(jest-)?react-native|@?react-navigation|react-navigation-redux-helpers)"
  ]
}

Back button

Here is a code snippet that demonstrates how the user might handle the hardware back button on platforms like Android:

import React from "react";
import { BackHandler } from "react-native";
import { NavigationActions } from "react-navigation";

/* your other setup code here! this is not a runnable snippet */

class ReduxNavigation extends React.Component {
  componentDidMount() {
    BackHandler.addEventListener("hardwareBackPress", this.onBackPress);
  }

  componentWillUnmount() {
    BackHandler.removeEventListener("hardwareBackPress", this.onBackPress);
  }

  onBackPress = () => {
    const { dispatch, nav } = this.props;
    if (nav.index === 0) {
      return false;
    }

    dispatch(NavigationActions.back());
    return true;
  };

  render() {
    /* more setup code here! this is not a runnable snippet */
    return <AppNavigator navigation={navigation} />;
  }
}