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:

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

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

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:

   Shell

   npm install jscodeshift -g
   

2. Copy the following snippet and run the command in your project's root directory:

   Shell

   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.

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>
);

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

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