Redux Persistence Pattern

Redux Persistence Pattern

Persist and rehydrate Redux state across browser sessions with redux-persist or manual localStorage strategies

When to Use

• Preserving user preferences, cart items, or draft content across page reloads
• Implementing offline-first features that need state survival
• Selectively persisting some slices while keeping others ephemeral
• Migrating persisted state when the schema changes between app versions

Instructions

1. Choose between redux-persist (full library) or manual persistence (listener middleware + localStorage). Use redux-persist for complex needs (transforms, migrations, multiple storage engines). Use manual for simple cases.
2. With redux-persist: Wrap the root reducer with persistReducer, create a persistor, and wrap the app with PersistGate.
3. Use a whitelist or blacklist to control which slices are persisted. Default to whitelist (explicit opt-in).
4. Add FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER to the serializable check ignore list — these are internal redux-persist actions.
5. Use createMigrate when the persisted state schema changes between versions.
6. Manual approach: Use the listener middleware to write specific state to localStorage on change, and preloadedState in configureStore to rehydrate on startup.

// redux-persist approach
import { configureStore } from '@reduxjs/toolkit';
import {
  persistStore,
  persistReducer,
  FLUSH,
  REHYDRATE,
  PAUSE,
  PERSIST,
  PURGE,
  REGISTER,
} from 'redux-persist';
import storage from 'redux-persist/lib/storage';
import { combineReducers } from '@reduxjs/toolkit';
import todosReducer from './features/todos/todos.slice';
import uiReducer from './features/ui/ui.slice';

const persistConfig = {
  key: 'root',
  version: 1,
  storage,
  whitelist: ['todos'], // Only persist todos, not UI state
};

const rootReducer = combineReducers({
  todos: todosReducer,
  ui: uiReducer,
});

const persistedReducer = persistReducer(persistConfig, rootReducer);

export const store = configureStore({
  reducer: persistedReducer,
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware({
      serializableCheck: {
        ignoredActions: [FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER],
      },
    }),
});

export const persistor = persistStore(store);

// App entry
import { PersistGate } from 'redux-persist/integration/react';
import { persistor, store } from './store';

function App() {
  return (
    <Provider store={store}>
      <PersistGate loading={<Spinner />} persistor={persistor}>
        <Root />
      </PersistGate>
    </Provider>
  );
}

Details

Manual persistence (simpler, no extra dependency):

// Rehydrate on startup
const preloadedTodos = JSON.parse(localStorage.getItem('todos') ?? 'null');
const store = configureStore({
  reducer: { todos: todosReducer },
  preloadedState: preloadedTodos ? { todos: preloadedTodos } : undefined,
});

// Persist on change via listener middleware
listenerMiddleware.startListening({
  predicate: (action, currentState, previousState) => currentState.todos !== previousState.todos,
  effect: (action, listenerApi) => {
    localStorage.setItem('todos', JSON.stringify((listenerApi.getState() as RootState).todos));
  },
});

State migrations: When adding or renaming fields between app versions:

const migrations = {
  1: (state: any) => ({ ...state, newField: 'default' }),
  2: (state: any) => {
    const { removedField, ...rest } = state;
    return rest;
  },
};

const persistConfig = {
  key: 'root',
  version: 2,
  storage,
  migrate: createMigrate(migrations),
};

Storage engines: redux-persist/lib/storage uses localStorage. For React Native, use @react-native-async-storage/async-storage. For session-only persistence, use redux-persist/lib/storage/session.

What NOT to persist: Loading states, error messages, ephemeral UI state (modals, tooltips), data that should be fresh from the server.

Source

https://github.com/rt2zz/redux-persist

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.