redux-persist

Redux Persist wraps an existing Redux reducer so its state is automatically saved to storage and restored on the next load, without changing how the rest of the app dispatches actions or reads state. It ships pluggable storage engines (localStorage/sessionStorage for web, and any AsyncStorage-compatible engine for React Native), configurable whitelist/blacklist filtering, versioned migrations for evolving state shapes, and swappable state reconcilers that control how restored state merges with a reducer’s initial state.

The library has been a staple of the Redux ecosystem since 2015, widely used on both web and React Native to bootstrap persisted state before rendering (via the bundled PersistGate component). A community-maintained ecosystem of transform packages layers on encryption, compression, and immutable-state support on top of the core serialization pipeline.

What You Get

• persistReducer — wraps any reducer to add automatic persistence and rehydration, requiring only a key and a storage engine to get started
• persistStore — creates a persistor object with .purge(), .flush(), .pause(), and .persist() lifecycle controls
• Pluggable storage engines — localStorage/sessionStorage out of the box, or any object exposing getItem/setItem/removeItem (e.g. AsyncStorage for React Native)
• Built-in state reconcilers (autoMergeLevel1, autoMergeLevel2, hardSet) controlling how restored state merges with a reducer’s initial state
• createMigrate for versioned state migrations when a persisted shape changes between app releases
• PersistGate React component that delays rendering children until rehydration completes
• Nested persists, whitelist/blacklist filtering, and a transform pipeline for customizing what gets serialized

Common Use Cases

• Keeping a logged-in user’s session or auth tokens available across browser refreshes without re-fetching from the server
• Persisting shopping-cart or form-draft state in a web app so it survives an accidental tab close
• Restoring app state instantly on cold start in React Native apps using AsyncStorage as the storage engine
• Migrating a persisted state shape safely across app versions using versioned migrations instead of wiping user data
• Selectively excluding sensitive or ephemeral slices of state (e.g. navigation, temporary UI state) from persistence via blacklist/whitelist

Under The Hood

Architecture persistReducer wraps a base reducer and intercepts a small set of internal action types (PERSIST, PURGE, FLUSH, PAUSE, REHYDRATE) rather than using Redux middleware, delegating the actual storage write to a “persistoid” object created by createPersistoid, which batches changed state keys through a throttleable interval before calling the pluggable storage engine’s setItem. persistStore creates a tiny internal Redux store purely to track per-key registration and rehydration bookkeeping, and exposes .purge()/.flush()/.pause()/.persist() by dispatching those same special action types back through the wrapped reducer — an unconventional inversion where storage side effects are triggered from reducer logic rather than middleware. State reconciliation is delegated to swappable reconciler functions, and storage engines are pluggable objects satisfying a small get/set/removeItem interface, giving reasonably clean separation between the reducer wrapper, the write-batching layer, the reconciler, and the storage engine, tempered by a few explicitly flagged unhandled edge cases in the core reducer.

Tech Stack Written in TypeScript (the large majority of the codebase, migrated from Flow in 2021), with redux as the only peer dependency and no runtime dependencies of its own. Built via tsc for commonjs and ES2015 module outputs and via Rollup (with Terser) for a UMD bundle, tests run under Ava with ts-node, mocking via Sinon and redux-mock-store, and linting/formatting via ESLint, Prettier, and a Husky/lint-staged pre-commit hook. A small React integration entry point (integration/react) ships the PersistGate component separately from the core.

Code Quality A dedicated tests directory covers the reducer state machine, persistor lifecycle, combined reducers, and flush behavior through several Ava spec files with supporting mock utilities. Configuration errors are caught explicitly in development (missing key or storage throws immediately), but storage write failures fall back to a single optional writeFailHandler with console logging in development and otherwise fail silently — there is no retry path. Naming and types are consistent throughout a well-defined types.ts, and CI runs via GitHub Actions, though the project’s own maintainers note the repo has had periods of low activity between maintenance transitions.

API Design The public surface is intentionally minimal: wrapping an existing reducer with persistReducer and calling persistStore on the resulting store is enough to get persistence with almost no boilerplate, and PersistGate removes the need to hand-write a loading gate around rehydration. Storage is abstracted behind swappable engines so the same API covers web and React Native without special-casing, nested persists allow per-slice storage/filtering rules, and a transform pipeline lets community packages add encryption, compression, or immutable-state support without touching the core. The pattern is now common (built into libraries like Redux Toolkit’s persistence helpers and Zustand’s persist middleware), so it reads as an influential, well-worn design rather than a novel one today.