HomeGuidesRecipesAPI ExplorerForumSupport
Partner Portal
Partner Portal

Migration guide to React SDK 3.0

This guide is primarily for users with prior experience using the React SDK v2.x.x looking to learn about the changes in the React SDK v3.0.0+ package. This page describes the changes to make in your existing applications when migrating to version 3.0.0+ of the React SDKs. For the full list of breaking and non-breaking changes to this version, see React SDK v3.0.0 change logs.

Overview

The React SDK v3.0.0+ packages have breaking changes for partners on previous integrations, so ensure you fully test your applications after migrating before going live. Some changes made to the React SDK include:

  • renaming of the ui-widgets-react package to sdk-react.
  • changing the sdk-api and sdk-react packages on the NPM directory.
  • deprecation of the entityId property on the MoniteSDK instance.
  • new implementation for localization and theming.

The following steps outline the process you must follow when migrating to our React SDK v3.0.0+.

Step 1: Update the packages

Due to the package renaming, you must update the packages on your application by uninstalling the deprecated React SDK dependencies and installing the new dependencies. To get started, follow the instructions to do so using your preferred package manager as shown:

Before: v2.x.x+

npm uninstall @team-monite/ui-widgets-react @team-monite/sdk-api
yarn remove @team-monite/ui-widgets-react @team-monite/sdk-api

After: v3.x.x+

npm install @monite/sdk-api @monite/sdk-react
yarn add @monite/sdk-api @monite/sdk-react

Step 2: Update imports from packages

In order to keep your code functioning after updating your package dependencies, you must change your import statements to use the updated package names for the new versions. You can update imports in either of two ways:

Update imports manually

Previously, SDK components and instances were imported from the @team-monite/ui-widgets-react and @team-monite/sdk-api packages. The following snippet shows the current convention for import statements from v3.0.0+:

- import { PayablesTable, Counterparts } from '@team-monite/ui-widgets-react';
+ import { PayablesTable, Counterparts } from '@monite/sdk-react';

- import { MoniteSDK } from '@team-monite/sdk-api';
+ import { MoniteSDK } from '@monite/sdk-api';

Using jscodeshift

Alternatively, you can use jscodeshift to automatically update imports in your project. jscodeshift is a toolkit for creating code transformations across multiple source files passed through it. Use the following steps to update package imports via jscodeshift:

  1. Install jscodeshift globally as shown:

    npm install jscodeshift -g
    
  2. Copy the following snippet and run the command in your project's root directory:

    jscodeshift --extensions=tsx,ts,js,jsx --parser=tsx -t "https://raw.githubusercontent.com/team-monite/monite-sdk/main/migrators/jscodeshift-transformer-migrate-to-version-3.ts" ./src
    

where ./src is the path to your project's main source code.

๐Ÿ“˜

If done successfully, all the imports from the @team-monite/ui-widgets-react and @team-monite/sdk-api package will be replaced with @monite/sdk-react and @monite/sdk-api respectively.

Step 3: Include the Dialog component

Following the deprecation of the layout prop on the CounterpartDetails, InvoiceDetails, and PayableDetails components, we introduced a new mechanism to handle the layout of these component. We created a Dialog wrapper component to contain the configuration of these components. The Dialog component has two propsโ€”open and alignDialogโ€”that determine the availability and alignment of its child component, respectively.

import { InvoiceDetails, Dialog } from "@monite/sdk-react";

...

// TODO: This component must be rendered within the MoniteProvider wrapper
return (
 <Dialog open alignDialog="right">
   <InvoiceDetails id="INVOICE_ID" />
 </Dialog>
);

If the alignDialog prop is not provided, the components will be aligned to the center of the page. For more information, see The Dialog component.

Additional updates to the React SDK

Theming and customization

The migration of Monite's React SDK from our proprietary design system to Material UI has been completed successfully. To customize SDK components, you must define your custom theme object and provide it as a second parameter to Material UI's deepmerge function. The first parameter must be the defaultMoniteLightThemeOptions object imported from the @monite/sdk-react package as shown:

import { MoniteProvider, defaultMoniteLightThemeOptions } from "@monite/sdk-react";
import { orange, red, green, blueGrey, grey } from "@mui/material/colors";
import { deepmerge } from "@mui/utils";

const customTheme = deepmerge(defaultMoniteLightThemeOptions, {
  palette: {
    mode: "light",
    primary: {
      main: "#f2f",
    },
    error: {
      main: red[900],
    },
  },
  typography: {
    fontFamily: "Comic Sans MS, Comic Sans, cursive, monospace",
    h2: {
      fontSize: "26px",
      fontWeight: "500",
    },
  },
});

const App = () => (
  <MoniteProvider theme={customTheme}>
     ...
  </MoniteProvider>
);

๐Ÿ“˜

From v3.0.0+, the underlying mechanism for customizing SDK components relies on Material UI's theming. For more information, see Theming and customization and Material UI Theming.

Localization

We updated properties of the locale object on the MoniteProvider wrapper. The currencyLocale property previously used in v2.x.x+ has been deprecated in favor of a new code property. The code property handles the usage of delimiters and decimal separators for different currency regions and must adhere to the BCP-47 language tag standard.

Before: v2.x.x+

<MoniteProvider
  locale={{
    currencyLocale: 'en-US',
    messages: {}
  }}
/>

After: v3.0.0+

<MoniteProvider
  locale={{
    code: 'en-US',
    messages: {}
  }}
/>