Mendix React Client

1 Introduction

In Studio Pro versions 10.7.0 and above, there is an alternative version of the Mendix Client written in React. The React version of the client is currently a beta feature. You can enable this React client in App Settings.

The React client replaces Dojo with React for the view layer. This change allows for improved performance, enables incremental loading, and future-proofs your application. For more information on these three aspects, see the sections below:

• Improved Performance
• Incremental Page Loading
• Future-Proof

Beyond those sections, consult the following major sections to leverage the React client to its fullest potential:

• Prerequisites – learn the prerequisites your app must fulfill in order to use the React client.
• Migration Guide – use guides to convert your application so it is ready for the React client.

1.1 Improved Performance

Web application performance is a key metric for quality apps. If a website does not open quickly or feels sluggish to use, many external users will abandon it immediately. For internal apps, smooth performance ensures employees can focus more on their work than on their tools.

Lighthouse (built into the Chrome browser) is a commonly used tool that measures app performance. It reports the overall performance of a web application and key indices that lead up to the performance score.

When comparing a conventional Mendix web application with the same application using the new React Client, we observe the following improvements:

Mendix believes the most important metric for most web applications is largest contentful paint, because it represents when the majority of the application has been loaded successfully. By this metric, the new React client performs 10% faster than the previous client – a significant change that requires no optimization work at all on the application model.

1.2 Incremental Page Loading

The second advantage of the React client becomes immediately apparent when your web app contains complex pages with multiple datasources. In the previous Mendix Client, the user just sees a progress indicator until the entire page is loaded. In the new React client, the core structure of your website is shown immediately and content is added as it is loaded. This way, your users can already see some loaded data or orient themselves in your app’s user interface instead of staring at a progress indicator. This psychological difference significantly improves the perceived speed of your application.

1.3 Future-Proof

Finally, the React client allows Mendix to clean up our client and remove many libraries that are no longer needed, such as the Dojo framework. While it was popular when we introduced in Mendix, it has now come out of fashion. By removing such dependencies in favor of modern frameworks, such as React, we can better ensure that your applications run stable and secure in your users’ web browsers.

2 Prerequisites

Review the prerequisites below that your application must fulfill before it can leverage the React client.

2.1 Mendix Version

The React client was introduced in Mendix 10.7.0 as a beta feature. It is planned to be released for general availability in Mendix 10.12.0.

2.2 Widgets

Widgets must fulfill the following requirements to be compatible with apps leveraging the React client:

• The widget must be a pluggable widget
• The widget must be compiled using the pluggable-widget-tools version 9.4.1 or above

2.3 JavaScript Actions

JavaScript actions must not use any of the following client APIs:

• The global symbol dojo
• The global symbol dijit
• The setting mx.modulePath
• The function mx.ui.openForm

These APIs are related to Dojo and are no longer needed. For opening pages, please use the nanoflow Show Page action instead.

Fore more information on React and APIs in Mendix, see our Mendix 10 React Client API documentation.

2.4 Enable React Client

To enable the React client for your Mendix project, make sure it fulfills the prerequisites above. Then, enable the React client in App Settings.

The migration mode will show warnings instead of errors for all incompatible widgets found in your project. This can help you explore and test the React client without being blocked by errors. When deploying an app leveraging the React client, we recommend setting React Client to Yes and resolving all errors before deploying.

3 Migration Guide

Read further for guides that allow you convert your app so it is ready for the React client.

3.1 Marketplace Components

Not all Mendix Marketplace components are ready for the React client. Refer to Marketplace Component React Status to see which of the most popular marketplace components are React ready. If a module or widget you are using is not on the list, test it for yourself then reach out to the authors to update it if not.

Mendix recommends refreshing all Marketplace components in your app before enabling the React client.

3.2 Dynamic & Static Image

The Dynamic Image and Static Image widgets are not supported in the React client. To use React, replace them with the universal Image widget. You can download the Image widget from the Mendix Marketplace.

To automatically convert a dynamic image or a static image, right-click the widget (or the error message) and select Convert to Image.

3.3 Reference Selector

The reference selector widgets (Reference Selector, Reference Set Selector, and Input Reference Set Selector) are not supported in the React client. To leverage React, replace them with the Combo Box widget. The combo box widget can be downloaded from the Mendix Marketplace.

To replace a reference selector widget, follow these steps:

1. Add a combo box widget next to the original widget.
2. Set the Attribute, Caption, and Label properties to match the original widget.
3. Set any other properties to match the original widget.

To replace a reference set selector widget, follow these steps:

1. Add a combo box widget next to the original widget.
2. Set the Attribute to the association that was used as data source in the original widget.
3. Set the Caption to the attribute used in the column of the original widget, or use an expression to reflect multiple columns.
4. Set the Label to a meaningful label for the attribute.

This will replace the table from the reference set selector with a more commonly used drop-down widget supporting multiple selection.

To replace an input reference set selector, follow these steps:

1. Add a combo box widget next to the original widget.
2. Set the Attribute to the association used as data source on the select page used by the original widget.
3. Set the Caption to the attribute used on the select page, or use an expression to reflect multiple columns.
4. Set the Label and any other properties to match the original widget.
5. Remove the select page.

This will replace the pop-up showing a table for selection with a more commonly used dropdown widget supporting multiple selection (see above).

We also recommended you replace drop down widgets with combo box widgets for a better user experience. This change is not required.

3.4 Data Grid

The data grid widget is not supported in the React client. To leverage React, replace it with the Data Grid 2 widget. The data grid 2 widget is part of the Data Widgets Module in the Mendix Marketplace.

To automatically convert a data grid widget to a data grid 2, right-click the widget (or the error message) and select Convert to Data Grid 2.

3.5 Template Grid

The template grid widget is not supported in the React client. It should be replaced with the Gallery widget. The gallery widget is part of the Data Widgets Module in the Mendix Marketplace.

To replace a template grid widget, follow these steps:

1. Add a gallery widget next to the original template grid widget.
2. Set up the gallery widget’s data source to match the original widget.
3. Configure the columns and any other properties to match the original widget.
4. Add any actions that items from your original widget as icon buttons to the content area.
5. Add any actions that do not affect rows as buttons to the gallery widget’s header.

3.6 Custom Widgets

Dojo widgets are no longer supported in the React client. They should be replaced with a pluggable widget based on React.

Converting a Dojo widget to a React widget requires JavaScript programming. Follow Build a Pluggable Web Widget: Part 1.

Pluggable widgets must be built with pluggable-widget-tools version 9.4.1 or higher. Follow these steps to update pluggable-widget-tools and rebuild your widget:

1. Open your widget folder in your text editor of choice.
2. Edit package.json.
3. Find the line containing "@mendix/pluggable-widgets-tools": "~[version]",.
4. Replace [version] with a newer version (for example 9.24.0).
5. Save the file.
6. Install the new dependencies by running npm install.
7. Build the widget by running npm run release.

3.7 Styling

The React client introduces some minor changes to the DOM structure of Mendix applications. These changes can have an impact on your styles as defined in SCSS. To avoid any issues, test your custom styles before deploying the updated application.

If your application’s navigation bar does not fill the entire screen, you are likely using an outdated version of the Atlas Core module. Please update it to the latest version to fix this.

3.8 JavaScript Actions

JavaScript actions should be mostly unaffected by React. Problems arise only if you use outdated actions or make extensive use of our Client API.

Problems in JavaScript actions are not captured by the consistency checker. To validate that JavaScript actions work with the React client, the checker should be executed with the React client active. Any errors reported by the Browser Console (Press F12 to access it) will help identify the problem.

If you encounter problems with platform-supported JavaScript actions (for example from the Nanoflow Commons module) make sure to update the module containing the action from the Marketplace. In most cases, this will resolve the issue. If it is not resolved, reach out to the maintainer of the module and let them know of the issue.