redux-persist

What is redux-persist?

redux-persist is a library that allows you to save the Redux store in persistent storage, such as local storage, session storage, or even custom storage engines. This helps in maintaining the state of the application across page reloads.

What are redux-persist's main functionalities?

Persisting Redux State

This feature allows you to persist the Redux state using a storage engine like local storage. The `persistReducer` function wraps your root reducer, and `persistStore` initializes the persistor.

const persistConfig = { key: 'root', storage }; const persistedReducer = persistReducer(persistConfig, rootReducer); const store = createStore(persistedReducer); const persistor = persistStore(store);

Rehydrating State

Rehydration is the process of loading the persisted state back into the Redux store when the application starts. This ensures that the state is restored to its previous state before the page was reloaded.

persistStore(store, null, () => { console.log('Rehydration complete'); });

Custom Storage Engines

You can use custom storage engines if the default local storage or session storage does not meet your requirements. This example shows how to create a noop storage engine for environments where local storage is not available.

import createWebStorage from 'redux-persist/lib/storage/createWebStorage'; const createNoopStorage = () => { return { getItem(_key) { return Promise.resolve(null); }, setItem(_key, value) { return Promise.resolve(value); }, removeItem(_key) { return Promise.resolve(); } }; }; const storage = typeof window !== 'undefined' ? createWebStorage('local') : createNoopStorage();

Other packages similar to redux-persist

redux-localstorage

redux-localstorage is another library that allows you to persist Redux state to local storage. It is similar to redux-persist but offers a more modular approach, allowing you to choose different storage adapters and serializers.

redux-persist-transform-encrypt

redux-persist-transform-encrypt is a transformer for redux-persist that encrypts your persisted state. This is useful if you need to store sensitive information securely. It works as an add-on to redux-persist, providing encryption capabilities.

redux-persist-cookie-storage

redux-persist-cookie-storage is a storage engine for redux-persist that uses cookies instead of local storage or session storage. This can be useful for server-side rendering or when you need to share state across different subdomains.

README

Redux Persist

Persist a redux store.

• Operates on a per reducer basis
• Performant out of the box (uses a time interator and operates on state partials)
• Knows as little as possible about your application state and reducer internals
• Supports any storage backend including localStorage, react-native AsyncStorage, or any conforming api

NOTE 0.2.8 switched to flux standard actions. If you are using custom rehydration be sure to update action.key => action.payload.key and action.data => action.payload.data

Implementing rehydration is very application specific. Check out some recipes.

Basic Usage

Basic usage requires adding three lines to a traditional redux application:

import { persistStore, autoRehydrate } from 'redux-persist'
const reducer = autoRehydrate(combineReducers(reducers))
const store = createStore(reducer)

persistStore(store)

For more complex rehydration, add a handler to your reducer:

case REHYDRATE:
  if(action.key === 'myReducer'){

    //remove transient state
    delete action.data.someTransientKey

    //expire old data
    if(action.data.someCache.date < Date.getTime() - 1000*60*60){
      delete action.data.someCache
    }

    //immutable data
    let someIndex = Immutable.List(action.data.someIndex)

    return {...state, ...action.data, someIndex}
  }
  return state

You may need to configure the persistance layer, or take action after rehydration has completed:

persistStore(store, {blacklist: ['someTransientReducer']}, () => {
  store.dispatch({type: 'REHYDRATION_COMPLETE'})
})

API

• persistStore(store, [config, callback])

  • store redux store The store to be persisted.
  • config object
    • blacklist array keys (read: reducers) to ignore
    • actionCreator action creator The rehydrate action creator. absent will use a default action creator which returns: { reducer, data, type: 'REHYDRATE}
    • storage object An object with the following methods implemented setItem(key, string, cb) getItem(key, cb) removeItem(key, cb)
  • callback function Will be called after rehydration is finished.

• autoRehydrate(reducer)

  • This is a higher order reducer that will automatically shallow merge the persisted state for each key.

• .purge(keys)

  • keys array An array of keys to be purged from local storage.

• .purgeAll()

  • Purges all keys.

Storage Backends

Use any storage backend including: localStorage (default), react-native AsyncStorage, or a conforming custom storage api.

React-Native Example

var { AsyncStorage } = require('react-native')
var { persistStore } = require('redux-persist')

persistStore(store, {storage: AsyncStorage}, () => {
  console.log('restored')
})

Motivations & Explanations

Conceptually redux-persist operates on a per reducer basis. This enables the persistance layer to know as little about the application as possible. This is important, reducers should be the single source of truth for your state manipulation.

It also enables great out of the box performance, as each save only operates on chunks of state, rather than the entire state object.

While auto rehydration works out of the box, individual reducers can opt in to handling their own rehydration, allowing for more complex operations like applying data transforms, or doing cache invalidation. Simply define a handler for the rehydrate action in your reducer, and if the state is mutated, auto rehydrate will skip that key.

Auto Rehydrate

Auto rehydrate is a higher order reducer that automatically rehydrates state. If you have a reducer that needs to handle its own hydration, perhaps with special time expiration rules, simply add a rehydration handler in your reducer, and autoRehydrate will ignore that reducer's keyspace.

Generally speaking if you have transient state that you do not want to rehydrate, you should put that in a separate reducer which you can blacklist.

NOTE: autoRehydrate does not currently support custom actionCreators

Implementation Notes

For performance
During Rehydration getItem calls are invoked once per key using setImmediate.
During Storage setItem calls are invoked only on keys whose state has changed, using a time iterator one key every 33 ms (i.e. 30fps)