Monite React SDK v4 migration guide

Overview

This guide provides step-by-step instructions on migrating to the latest version of the Monite React SDK. Please read carefully and ensure all steps are followed to avoid potential issues.

Upgrade steps

1
npm uninstall @monite/sdk-api

1
- import { ... } from '@monite/sdk-api';
2
+ import { ... } from '@monite/sdk-react';

1
npm install @monite/sdk-react@latest

New MoniteProvider syntax

The @monite/sdk-api package has been deprecated. All API calls are now part of the main @monite/sdk-react package.

Also, the MoniteSDK object that was used to initialize the MoniteProvider has been removed. The MoniteProvider.monite prop now expects a plain JavaScript object instead of a MoniteSDK instance.

The following example shows the old and new syntaxes.

1
import { MoniteProvider } from "@monite/sdk-react";
2
3
const monite = {
4
  apiUrl: "https://api.sandbox.monite.com/v1",
5
  entityId: "ENTITY_ID",
6
  fetchToken: fetchToken,
7
};
8
9
function App() {
10
  return (
11
    <div className="App">
12
      <MoniteProvider monite={monite}>
13
        ...
14
      </MoniteProvider>
15
    </div>
16
  );
17
}
18
19
export default App;

Theming update

Key changes

• No more Material UI. The new theme object is a custom solution and no longer uses the Material UI theme specification.
• palette is now colors. The palette object has been replaced by a flatter colors object. Color definitions are now a single string value instead of an object with main and contrastText.
• New top-level properties. borderRadius and spacing have been added to control general UI metrics.
• Simplified typography. Typography variants have been standardized, and values are now primarily numbers instead of strings.

Migration steps

Follow these steps to convert your old customTheme object to the new format.

1. Update color definitions (palette → colors)

The palette object is now colors. You’ll need to map your old color values to the new, simplified keys:

• Take the main value from your old color objects (e.g. palette.primary.main).
• Assign this string directly to the new color key (e.g. colors.primary).

1
const newTheme = {
2
  colors: {
3
    primary: "#42a5f5",      // from palette.primary.main
4
    background: "#e3f2fd",   // from palette.background.paper
5
    text: "#000",            // from palette.text.primary
6
    // secondary, neutral, info, etc. would be added here if needed
7
  },
8
};

2. Update typography

The typography object is similar but has key differences in its variants and value types.

• Value types: fontSize and fontWeight should now be numbers, not strings (e.g. 500 not "500"). lineHeight remains a string with a px unit.
• Variant names: Some variants like button have been removed in favor of more semantic names like body1 or body2. You’ll need to map your old styles to the most appropriate new variant.

1
const newTypography = {
2
  fontFamily: "Comic Sans MS, Comic Sans, cursive, monospace", // remains the same
3
  fontSize: 16, // Add a base font size
4
  h2: {
5
    fontSize: 26,       // Changed to number
6
    fontWeight: 500,    // Changed to number
7
    lineHeight: '32px', // Add a line-height
8
  },
9
  // 'button' is deprecated. Apply styles to 'body1' or another variant instead.
10
  body1: {
11
    fontSize: 16,
12
    fontWeight: 500, // Matched from 'button' (fontWeight '300' in old example was likely a typo)
13
    lineHeight: '24px',
14
    // 'textTransform' is no longer a theme option.
15
  },
16
};

3. Add new global properties

Add the new borderRadius and spacing properties at the top level of your theme object. You can use the default values to start.

1
const newTheme = {
2
  borderRadius: 6,
3
  spacing: 8,
4
  colors: { ... },
5
  typography: { ... },
6
};

❌ Unsupported & deprecated properties

The following properties from the old Material UI theme are no longer supported:

• palette.mode: The light/dark mode toggle is not supported anymore.
• palette.*.contrastText: The new colors object does not have a field for contrasting text color. This is now handled internally.
• palette.background.paper: This is simplified to colors.background.
• palette.text.secondary: This is simplified to colors.text.
• typography.button: This variant has been removed. Use body1 or body2 instead.
• typography.*.textTransform: This CSS property can no longer be configured through the theme.

Complete theme migration example

Here is a full conversion of the sample customTheme from the old format to the new format.

1
const customTheme = {
2
  // 1. Add new global properties
3
  borderRadius: 6,
4
  spacing: 8,
5
6
  // 2. Convert 'palette' to 'colors'
7
  colors: {
8
    primary: '#42a5f5',
9
    success: '#1fb42b',
10
    background: '#e3f2fd',
11
    text: '#000',
12
    // Fill in other colors or use defaults
13
    secondary: '#707070',
14
    neutral: '#707070',
15
    info: '#3737FF',
16
    error: '#CC394B',
17
  },
18
19
  // 3. Update typography
20
  typography: {
21
    fontFamily: "Comic Sans MS, Comic Sans, cursive, monospace",
22
    fontSize: 16, // Set a base font size
23
    h2: {
24
      fontSize: 26,       // Converted to number
25
      fontWeight: 500,    // Converted to number
26
      lineHeight: '32px', // Add required line-height
27
    },
28
    h3: {
29
      fontSize: 24,       // Using default size
30
      fontWeight: 600,    // Using default weight
31
      lineHeight: '32px', // Approximate from old 1.13 ratio
32
    },
33
    // The 'button' and 'textTransform' properties are removed.
34
    // Apply relevant styles to a new variant like 'body1'.
35
    body1: {
36
      fontSize: 16,
37
      fontWeight: 400, // Default weight
38
      lineHeight: '24px',
39
    },
40
  }
41
};

Troubleshooting

If you encounter any issues during or after the migration, refer to the full Monite SDK documentation for usage tips and FAQs.

Support

For further assistance, contact our support team.