How to migrate store persisted by redux-persist?

Intro

Recently, I got caught in a pitfall about redux-persist when developing react-native application.
It 's because two reasons. The one is the redux store in app has complicated shape. Another is redux-persist's migration sample document is very simple and I can't find any other douments about migration.

If you read the doc and figure it out, you don't perhaps need to read following.
But you have questions about how to migrate store or how migration works, this article would be helpful.

Prerequisite

This article based on following version.

yarn: v1.13.0
redux-persist: v5.10.0

First Step

All codes in this article is here.
This repo made by create-react-app and already setup.

Please clone the repo and checkout v1.0.0.

git clone https://github.com/sasurau4/sample-redux-persist-migration.git
cd sample-redux-persist-migration
git checkout v1.0.0

Starting development server following commands.

yarn install
yarn start

Then automatically open new tab on your browser! First step is done🎉

Inspect what happen in app

You would see very simple app consists of counter and favorite fruit picker.
Play with the app by increment or decrement or choose your favorite fruit!
Reload the page after playing. What happens to the app?

The state of the app will be the same as before the reload!
It's thanks to the redux-persist.

What happen in the app? Go to inspect it.

I usually use Google Chrome. I use it for explanation too.

Open your developer tools and see like following.

You can find persist:root key in local session and _persist key inside the value.
It shows redux-persist serialize our reducers by JSON.stringify.
You can see code
_persist is meta data added by redux-persist.

If no version specified the config, the library recognize the reducer as minus 1 version.

You can see the persisted data in local storage sync to the state of the app when change something!

So, go to the main question, migrate.

Store Migration

Keep te webpack-dev-server running and enter following command.

git checkout v2.0.0

What happened to the app?

The favorite animal item appear in the app and some log in the console!
It's the success of redux-persist migration.

The migration setting is following extracted here.

...
const migrations = {
  0: state => {
    return {
      ...state,
      favorite: {
        ...state.favorite,
        animal: 'Tiger',
      },
    };
  },
};

const persistConfig = {
  key: 'root',
  version: 0,
  storage,
  debug: true,
  migrate: createMigrate(migrations, { debug: true }),
};
...

Migrated state has favorite animal as Tiger, so you see favorite animal as Tiger in the app!
Check the version in _persist, you'll find version 0.

Next, checkout to master. What happened?

You see I don't like fruit! message on the app!
The migration of v0 to v1 succeeded.

The code is here

...
const migrations = {
  0: state => {
    return {
      ...state,
      favorite: {
        ...state.favorite,
        animal: 'Tiger',
      },
    };
  },
  1: state => {
    return {
      ...state,
      favorite: {
        animal: state.favorite.animal,
      },
    };
  },
};
...

You find the difference of missing state.favorite between key of 0 and 1.
Migrated store of version 1 already doesn't have fruit key in Favorite reducer.
So, you see "I don't like fruit!" message.

If you want to more playing with the app, you checkout any version what you want.
If you want to know more details about redux-persist, I recommend checking the repo
It's very helpful and well documented.

Conclusion

redux-persist is very useful library when you think about persist store.
It provides simple and powerful APIs!

If you find any mistakes or misunderstanding, please pointed it out to me. 🙏

Thanks for reading!

Note: After posted this article, I found the article told same theme from redux-persist's README!
It's be helpful too! Please read it if you need.