Part 1: Why?
1.1 Why Persist
- Not all state is well represented by the url. e.g. user preferences are not appropriate to store in the url as a url is intended to be shareable.
- It is time consuming and expensive to refetch data every time the page loads. If everything is stored on disk, any given page can be refreshed in milliseconds rather than seconds.
- There is no url in native contexts. This means the patterns you are used to on the web do not map well to iOS / Android / Electron apps.
- Offline First. Your users do not have stable internet connections. Persistence is the first step of offline support.
1.2 Why Redux Persist
There is no two ways about it, persistence is hard. We are talking about an ever changing blob of state that travels through time at discrete intervals. And when one of these state blobs shows up, the application needs to process it. But the blob could be days, weeks or years old!
Redux Persist provides a consistent, performant, and structured way to persist state.
Part 2: Architecture
2.1 The Component Parts
The “persistence layer” is actually two stateful reactive objects, plus a higher order reducer.
The persistor can be thought of as the persistence lifecycle orchestrator. This is the object returned by persistStore, it kicks off the persistence process via a PERSIST action. It also creates register and rehydrate methods which will be used to register each persistoid, and dispatch the actual rehydrate action respectively.
The persistoid is the actual state sink. It is quite simple, just a function which takes state as an argument and handles quickly and efficiently writing that state to disk.
The persisted reducer is a small wrapper around any other reducer that can be best explained by its lifecycle:
1. picks up the PERSIST action
2. creates the persistoid
3. it begins reading state from disk
4. fires the REHYDRATE action
5. whenever state changes, notify the persistoid
6. additionally it handles the PURGE action for clearing stored state.
2.2 Whats new in Redux Persist v5
- code splitting reducers
- better integration story for libs (e.g. redux-offline)
- ability to colocate persistence rules with the reducer it pertains to
- first class migration support
- enable PersistGate react component which blocks rendering until persistence is complete (and enables similar patterns for integration)
- nest persistence configuration
Redux? Thats not cool anymore
Actually it is pretty great, exactly for this reason. It provides a consistent and simple interface to work with state. In fact redux-persist uses a redux store internally to power the persistor! Thats means a consistent story around extensibility, and the ability to use redux-devtools to debug any tricky issues internal to the persistence layer.
Vanilla Redux requires a ton of ceremony to use. Between actions, reducers, selectors, connectors, the simplest feature might touch 4+ files. Our hope is that redux-persist fits into a new set of libraries that allow for a more ergonomic usage of redux.
Without sacrificing simplicity, nor type safety, it should be possible to define your state declaratively and receive back the methods necessary to build your app.
Redux Persist v5 solves one small part of this problem: declarative persistence.
npm i -S redux-persist@next
Please help test v5 here. Note the api has changed so please check the readme. Open an issue if you have questions or concerns. PRs are welcome.
Huge Thanks to
214k dl/mo, yet only ~%5 of all redux downloads!