Redux Migrations

When making changes to the frontend applications redux store, developers must create migrations when the shape of the redux state changes. This is incredibly important when adding new state properties that are dependant on data being populated by the backend.

Each migration should be able to stand on its own in its own migration file, and each migration should if possible also provide state data. In the case of a code-table for example, it would be recommended to include any/all new items that would be inserted into the database via flyway.

To create a migration the developer will need to perform the following steps:

1. in the redux store folder create a new migration file in the migrations folder
2. create and export a new migration object

export const ExampleMigration = {
   1: (state: any) => {
      return {
         ...state,
         codeTables: {
            ...state.codeTables,
            example: [
               {
                  name: "EXAMPLE01",
                  shortDescription: "Example 01",
                  longDescription: "Example - 01",
                  displayOrder: 1,
                  isActive: true,
               },
               {
                  name: "EXAMPLE02",
                  shortDescription: "Example 02",
                  longDescription: "Example - 02",
                  displayOrder: 2,
                  isActive: true,
               }
            ],
         },
      };
   },
};

In this example we are returning a new object with a key pair where the key is the version number, and the pair is a function that takes in a state object and returns a new state object. Its this state that you will need to modify in order to create your migration. In the example the state is being returned with a new property on the codeTables property called: example and in addition to creating the new property we are also populating the new property with an array of new code-table objects

3. add your migration to the redux-persist migration script located in the migrations.ts file in the root of the store folder in the frontend project

import { ExampleMigration } from "./migrations/example";

const BaseMigration = {
   0: (state: any) => {
      return {
         ...state,
      };
   },
};

let migration = {...BaseMigration}
migration = {...migration, ...ExampleMigration }

export default migration;

in this example the user is importing their migration ExampleMigration and then is appending it to the base migration. It is important that migrations are added in the correct order otherwise there will be unexpected side effects where the application may/will cease to function properly and render a white screen. To add an additional migration, the same pattern needs to be followed, import your migration file and append to the base migration object by either adding an additional spread to the example, or by spreading your migration independently as in the following example:

import { ExampleMigration } from "./migrations/example";
import { SecondExampleMigration } from "./migrations/second-example";

const BaseMigration = {
   0: (state: any) => {
      return {
         ...state,
      };
   },
};

let migration = {...BaseMigration}
migration = {...migration, ...ExampleMigration }
migration = {...migration, ...SecondExampleMigration }

export default migration;

4. once the migrations have been added, one last step needs to be done, and that is to increase the version number in the persistConfig of our redux store. You'lll need to update the store.ts file and increase the version number of the persistConfig object. This version number must be the same value used for your key in your key:pair. That said if creating a new version 2 the updated persistConfig should be as follows:

const persistConfig = {
   key: "enforcement",
   storage,
   blacklist: ["app"],
   whitelist: ["codeTables"],
   version: 2,
   debug: true,
   migrate: createMigrate(migration, { debug: false }),
};

After your migration is created perform a refresh and the application will update its redux store to include your new state changes. You can verify that your changes have been migrated properly via the ReduxDev Tools extension. You'll be able to see your changes by selecting the last redux action (selected in blue), clicking the state button (selected in red), and selecting the tree view tab (selected in green). You should see the following/similar:

What you're looking for is your state changes, but just as importantly the _persist property should show that your version number is the same as your updated config value.