Native App Prerequisites and Troubleshooting

Last modified: November 5, 2024

Introduction

Developing mobile apps with Mendix requires some additional considerations. This guide explains the prerequisites of mobile development and helps you get started:

  • The Prerequisites section explains how to prepare for developing, deploying, and accessing mobile apps with Mendix
  • The Getting the Make It Native App section explains how to download the Make It Native App, which you can use to test your native mobile apps during development
  • The Troubleshooting Common Mobile Issues section explains port forwarding, WiFi settings, and other common troubleshooting issues

Prerequisites

Progressive Web Apps

There are no special requirements for developing, deploying, and accessing Progressive Web Apps (PWAs) with Mendix.

Native Mobile Apps

Native mobile apps are not run in the device browser like web-based Mendix apps. Instead, a native app is built for each mobile operating system it should run on resulting in an APK or IPA file, which are then installed on the device. This introduces several special considerations:

  • Developer Preview: When developing a native mobile app, a special app called Make It Native is required to preview the app. It is not possible to preview it in the browser or directly in Studio Pro using Design Mode.
  • Build Native App: For building native apps, we provide a tool called Build Native App. This tool must be configured and run each time a new build is created. Build Native App is not supported on Studio Pro for Mac. Build Native App updates itself automatically by downloading new versions from AWS.
  • Native Template: Build Native App needs to download the Native Template from GitHub. This template contains the React Native project that is used to build the native app for iOS and Android.
  • Dependencies: The Native Template makes use of several open-source projects, including React Native. These must be downloaded from several external services including npm, gradle, and Cocoapods.
  • Building: Once prepared using Build Native App, the Native Template can be built for each target mobile operating system. Building can be done locally by downloading the mobile operating system’s IDE or remotely using a third-party continuous integration and delivery (CI/CD) platform. For building remotely, a GitHub account and an AppCenter account is required.
  • Deploying: Most mobile devices refuse to install APK/IPA files without additional steps. At minimum, the file must be signed to identify its developer and prevent manipulation. Furthermore, for iOS and recent versions of Android, the app must be published via the official mobile operating system’s store or a mobile device management (MDM) system.
  • Connectivity: When running a Mendix native mobile app, it must connect to the Mendix Runtime at least once during startup. If no connection can be established, an error is shown. Connectivity is also needed to run microflows and to synchronize data.

Air-Gapped Development

Developing and building native mobile apps requires access to several online resources. Without whitelisting these resources, a native mobile build will fail.

For development:

  • To preview their apps, developers need to be able to connect their mobile device running Make It Native to their Laptop running Studio Pro on ports 8080 and 8083.

For building:

  • Download updates from AWS: https://appdev-mx-cdn.s3.amazonaws.com/native-builders/latest.exe
  • Determine which native template version to download: https://raw.githubusercontent.com/mendix/native-template/master/mendix_version.json
  • Download the native template from GitHub: https://github.com/mendix/native-template/archive/refs/tags/*.zip
  • Upload the project to GitHub (optional): https://api.github.com/
  • Start AppCenter Pipeline (optional): https://api.appcenter.ms/v0.1/

In some situations, it can be beneficial to designate a single machine for building native mobile apps or outsourcing the process to a partner.

Getting the Make It Native App

The Make It Native app allows developers to preview, test, and debug native mobile apps in conjunction with Mendix Studio Pro. This app is available for both Android and iOS devices.

Depending on the Mendix version used to build your app, you have to use a different version of Make It Native. The following list explains which version to use:

  • Latest Mendix Version - Latest version of Make It Native 10 (Android, iOS)
    • Please note that the latest version of Make It Native 10 is offered in online stores’ beta version programs. Simply follow the instructions on those sites to download and install the latest version of MIN 10.
  • 10.12.x – Make It Native 10 MTS (Android, iOS)
  • 10.6.x to 10.11.x – These versions are no longer supported by Make It Native. Please use MIN 9 LTS (below) or 10 MTS (above) instead, or make your own custom MIN app from open source.
  • 9.24.0 to 10.5.x – Make It Native 9 LTS (Android, iOS)
  • 8.18.x – Make It Native 8 LTS (iOS)
  • Other – Creating a Custom Developer App or Building Your Own Make It Native App

For information on which mobile operating systems are supported by the Mendix native mobile apps, see the Mobile Operating Systems section of System Requirements.

Download the latest version of Make It Native 10 using these QR codes:

Android iOS
Android QR Code
iOS QR Code
Latest Version Latest Version

Download the MTS version of Make it Native 10 using these QR codes:

Android iOS
Android QR Code
iOS QR Code
MTS Version MTS Version

Using the Latest Version of Make It Native

The latest version of Make It Native app receives monthly updates, and is compatible exclusively with the latest minor release of Mendix. We recommend using this version only if you intend to update your application regularly.

To access the latest version of Make It Native, you must join our official beta testing programs on the Google Play store and the Apple App Store. To do so, click the relevant links above and follow the instructions.

Note that it is not possible to install both Latest and MTS versions on the same device.

Recommendations

When working with applications on a Long-Term Support (LTS) version of Mendix, use the corresponding LTS version of Make It Native. All patch versions of the Mendix LTS version can be used.

When working with applications on a Mid-Term Support (MTS) version, it is important to anticipate updating your application every 6 months. The MTS version of Make It Native exclusively supports the most recent MTS version of Mendix and receives updates one month after a new Mendix MTS version is released. We recommend performing the update during this month and using the latest version of Make It Native during the update process.

Only use the latest version of Mendix if you are prepared to update your application every month. The latest version of Make It Native only supports the latest version of Mendix and is updated monthly.

If you want to use a custom version of Mendix you can always create a Custom Developer App or build your own Make It Native App for that version of Mendix.

Troubleshooting Common Mobile Issues

Mendix strives to make building and running native mobile apps as simple as possible. But because some complexity is inherent in making apps, problems can come up. If you are having issues while building or running native mobile apps, please consult the sections below to see if your issue has already been solved.

Make It Native App

To troubleshoot issues related to the Make it Native app, see the sections below.

Port Issues

Mendix recommends keeping the Runtime port in your configuration on 8080. If you change it, do not change it to 8083, because that is designated for app packaging.

Wifi Network Settings

If you are using Windows, make sure your WiFi network is set to Private. Windows often sets WiFi to Public by default, which blocks incoming connections.

Error: Unable to Load Script

Depending on your device settings and network characteristics, the Make it Native app can fail to connect to the runtime. If so, the Make it Native app can show the following error messages:

  • Unable to load script:

    unable to load script

  • Cannot detect your runtime:

    cannot detect runtime

These failures are often caused by a firewall blocking your device from accessing your laptop. In such cases, attempts to open the runtime URL from a mobile browser will also fail. To mitigate these issues, please make sure your firewall allows incoming traffic to your laptop on the runtime and native packing ports (8080 and 8083 by default). Instructions on how to do this differ per firewall. Mendix recommends you consult your firewall administrator.

For the Windows Defender firewall, the most common firewall, do the following:

  1. Make sure that your computer and the mobile device are connected to the same network.

  2. Make sure that incoming connections are allowed by doing the following:

    1. Open Firewall & Network Protection settings in Windows.
    2. Go to Advanced Settings.
    3. Select the Inbound Rules and scroll to the Mendix Native Mobile entries.
    4. For each Node.js entry, note their values in the Program column. They should all have a green check mark in front of them.
    5. If the Program column shows a Mendix installation directory, then there should be a green icon in front of the entry. If this is not the case, double-click the entry and select Allow the connection:
    inbound rules

  3. Windows distinguishes between two types of networks: private and public. Windows Defender Firewall applies stricter regulations for public networks. If, and only if, you are connected to a trusted network, configure the network as Private on your computer.

Error: Unable to Detect Studio Pro

If your port forwarding settings are correct but you still get an error that the Make It Native app cannot detect Studio Pro, please reinstall the Make It Native app on your mobile device.

Strict Company Policies Prevent Your Connection

If your company has strict network policies which do not allow you to open the ports Mendix requires, here are 3 alternate approaches you can try:

  • Connect your PC via Wifi to a personal hotspot on your mobile phone, then look up your PC’s IP address and connect to http://{YOUR PC'S IP ADDRESS}:8080 from the mobile phone

  • Install the Make It Native app or a custom developer app on an Android emulator (for example BlueStacks), then connect to http://localhost:8080

  • Tunnel the ports from your desktop to your Android device via USB by executing the following commands from your shell (requires Android Studio):

    adb reverse tcp:8080 tcp:8080
adb reverse tcp:8083 tcp:8083

Use Make It Native 9 with an Older Version of Mendix 9

The latest version of Make It Native 9 is only compatible with versions of Mendix 9.24.0 and above. To develop with older versions of Mendix 9, you can create a custom developer app by following this guide. Note that a custom developer app can be used to develop multiple older Mendix apps as long as no custom dependencies are introduced.

Configure Parallels

To use Studio Pro on a Mac device, you will first need to install and configure Parallels. For more information, see Configuring Parallels.

Avoid Network or Cloud Folders

Storing a Mendix project on a network drive or in a cloud folder (such as those provided by OneDrive or Dropbox) is not recommended. Storing your projects in such folders will significantly slow down Studio Pro and cause errors when trying to run projects containing a native mobile profile. Note also that projects with a native mobile profile can only be started from drive C:.

If your home directory is managed by OneDrive, create a new folder on your computer outside of your home directory (for example C:\Mendix) and place the Mendix projects in there.