Redux Flipper Middleware

2.0.3 verified Thu Apr 23 auth: no javascript

redux-flipper is a Redux middleware designed to integrate Redux state and action debugging directly with the Flipper desktop client. It works in conjunction with the `flipper-plugin-redux-debugger` to visualize Redux store changes in real-time within React Native applications. The current stable version is 2.0.3, which supports Redux v5 and has relaxed peer dependency requirements for `react-native-flipper` and `react-native`. The package generally follows the release cadence of its companion Flipper plugin. Key differentiators include its ability to whitelist or blacklist specific state keys and actions, resolve cyclic references in the state (though with a performance warning), and its straightforward integration process for React Native applications, particularly those using `react-native` >= 0.62.

Common errors

error Redux Debugger plugin not showing up in Flipper desktop client ↓

cause The `flipper-plugin-redux-debugger` desktop plugin might not be installed or enabled in Flipper, or there could be a connection issue with your React Native app. The middleware might also not be correctly added to your Redux store, or not activated in a `__DEV__` environment.

fix

1. Ensure flipper-plugin-redux-debugger is installed and enabled in your Flipper desktop client via Manage Plugins > Install Plugins. 2. Verify your React Native app is connected to Flipper. 3. Check that redux-flipper middleware is correctly applied to your Redux store, preferably within an if (__DEV__) block.

error TypeError: Cannot read property 'default' of undefined at Object.<anonymous> (App.js:X:Y) ↓

cause This usually happens when `require('redux-flipper')` is used without `.default` to access the default export, or if `redux-flipper` is not correctly installed or resolved by the module system.

fix

When using CommonJS require, ensure you access the default export with .default: const createDebugger = require('redux-flipper').default;. If using ESM, import createDebugger from 'redux-flipper'; is the correct syntax.

error TypeError: Cyclic object value ↓

cause Your Redux state contains objects with circular references, which `redux-flipper` (and JSON serialization in general) cannot handle by default.

fix

Either refactor your Redux state to eliminate cyclic references, or enable the resolveCyclic option as a temporary measure: createDebugger({ resolveCyclic: true }). Be aware of potential performance impacts when enabling resolveCyclic. Consider using stateWhitelist to only debug specific parts of the state.

Warnings

breaking Version 2.0.0 was a major release to align with `flipper-plugin-redux-debugger` 2.0.0, fixing connection issues and `undefined` actions. Ensure your `flipper-plugin-redux-debugger` is also updated to v2.0.0 or higher for compatibility. ↓

fix Update `flipper-plugin-redux-debugger` to version 2.0.0 or later in your Flipper desktop client (`Manage Plugins > Install Plugins`).

gotcha Enabling `resolveCyclic: true` to handle cyclic references in your Redux state can significantly impact application performance. It is intended as a temporary debugging solution, and restructuring your Redux state to avoid cyclic references is the recommended long-term approach. ↓

fix Avoid cyclic references in your Redux state. If strictly necessary, use `createDebugger({ resolveCyclic: true })` but monitor performance. Prefer `stateWhitelist` to reduce the amount of state being serialized.

gotcha The middleware is typically intended for development environments. It's crucial to conditionally apply `redux-flipper` using `if (__DEV__)` to prevent unnecessary overhead and potential exposure of debugging information in production builds. ↓

fix Wrap the `createDebugger()` middleware instantiation and addition to your middleware array within an `if (__DEV__) { ... }` block to ensure it's only active in development builds. Example: `if (__DEV__) { middlewares.push(createDebugger()); }`

gotcha For React Native applications older than version 0.62, Flipper integration requires manual setup steps in the native (iOS/Android) projects. Automatic Flipper support is only enabled by default for `react-native` >= 0.62. ↓

fix Refer to the official Flipper documentation for manual setup steps for React Native versions below 0.62: `https://fbflipper.com/docs/getting-started/react-native.html#manual-setup`.

Install

npm install redux-flipper

yarn add redux-flipper

pnpm add redux-flipper

Imports

createDebugger

wrong

import { createDebugger } from 'redux-flipper';

correct

import createDebugger from 'redux-flipper';

The `createDebugger` function is the default export of the package.

createDebugger
wrong
```
const createDebugger = require('redux-flipper');
```
correct
```
const createDebugger = require('redux-flipper').default;
```
When using CommonJS `require`, the default export is accessed via `.default`. This pattern is typically used inside `if (__DEV__)` blocks.
ReduxFlipperConfig
```
import type { ReduxFlipperConfig } from 'redux-flipper';
```
Useful for type-checking the configuration object when using TypeScript.

Quickstart

This code demonstrates how to integrate `redux-flipper` middleware into both a traditional Redux store and a Redux Toolkit store, including common configuration options for state whitelisting/blacklisting and conditional `__DEV__` inclusion.

import { createStore, applyMiddleware } from 'redux';
import { configureStore } from '@reduxjs/toolkit';
import createDebugger from 'redux-flipper';

// Example Root Reducer (replace with your actual reducer)
const RootReducer = (state = { count: 0 }, action) => {
  switch (action.type) {
    case 'INCREMENT':
      return { ...state, count: state.count + 1 };
    default:
      return state;
  }
};

const middlewares = [
  /* other middlewares like redux-thunk or redux-saga */
];

if (__DEV__) {
  // Using the ESM import for createDebugger
  middlewares.push(createDebugger({
    stateWhitelist: ['user'], // Example: only log 'user' state changes
    actionsBlacklist: ['SET_THEME'], // Example: ignore 'SET_THEME' actions
    resolveCyclic: false, // Default is false, enable only if necessary
  }));
}

// Standard Redux store setup
const store = createStore(RootReducer, applyMiddleware(...middlewares));

// Redux Toolkit store setup example
const toolkitStore = configureStore({
  reducer: RootReducer,
  middleware: (getDefaultMiddleware) => {
    const defaultMiddlewares = getDefaultMiddleware();
    return __DEV__ ? defaultMiddlewares.concat(middlewares) : defaultMiddlewares;
  },
});

console.log('Redux store initialized. Open Flipper to debug.');

// Example dispatch to see actions in Flipper
store.dispatch({ type: 'INCREMENT' });
store.dispatch({ type: 'SOME_OTHER_ACTION', payload: 'test' });