Redux Persist is a library that enables Redux applications to persist their state to storage and rehydrate it on subsequent loads. Written in TypeScript, the library provides middleware and reducer enhancement utilities that allow developers to automatically save Redux store state to browser storage, React Native storage, or other custom storage engines, then restore that state when the application restarts.
The core functionality centers on two main functions. The persistReducer function wraps a Redux reducer and enhances it to handle persistence logic, accepting configuration for which parts of state to persist through whitelist and blacklist options. The persistStore function wraps a Redux store and returns a persistor object with methods to control persistence behavior, including purge to clear stored state, flush to immediately write pending changes, pause to stop persistence temporarily, and persist to resume it. The library also provides PersistGate, a React component that delays rendering the application until persisted state has been fully rehydrated, preventing UI flashes from incomplete state.
A critical feature is state reconciliation, which determines how persisted state merges with initial state when the application loads. Redux Persist ships with three reconcilers. The default autoMergeLevel1 performs a shallow merge one level deep, preserving initial state properties not present in persisted state. The hardSet reconciler completely replaces initial state with persisted state, useful for nested persist configurations. The autoMergeLevel2 reconciler extends merging to two levels deep for more complex state structures.
The library supports migrations through a general-purpose migrate configuration option that transforms stored state before reconciliation, enabling developers to update persisted state schemas across application versions. Redux Persist also provides a createMigrate utility for synchronous migrations. Transforms allow customization of what gets persisted and how, with the ecosystem including separate libraries for compressing state, encrypting sensitive data, filtering subsets of state, and handling immutable data structures.
Bug reports and stale issues represent the most common issue labels, with some issues requiring test repositories for reproduction.
The repository underwent significant modernization in 2021. In October 2021, the codebase migrated from Flow type annotations to TypeScript as part of infrastructure upgrades, and the project moved from TravisCI to GitHub Actions for continuous integration.
The v6 release introduced no breaking changes for web applications but required React Native users to explicitly pass their storage engine. The library integrates with the broader Redux ecosystem and is classified across multiple domains including local storage, offline support, data synchronization, session management, and platform compatibility for both web and React Native environments.
