Build a Mendix Native Mobile App Locally using the Mendix Native Builder

Last update: Edit

1 Introduction

By default when building your native mobile app binaries, Mendix uses Visual Studio App Center as a service so that users can build without having to install tools like XCode or Android Studio. However, there are cases when using App Center is not allowed or possible. In those situations, you can build your apps locally.

Follow the sections below through Building Your Native App to complete your builds. To go beyond those instructions, see Adding Dependencies and Removing Dependencies sections below. These sections will allow you to further customize your local builds.

2 Prerequisites

Before starting this how-to, make sure you have completed the following prerequisites:

For iOS builds:

For Android Builds:

3 Use Mendix Native Mobile Builder to Set Up Your Local App

  1. Run Mendix Native Mobile Builder from your app:

    Start Mendix Native Mobiler Builder
  2. When Mendix Native Mobile Builder launches you will see the home screen:

    Mendix Native Mobile Builder Home Screen
  3. Select Build app for distribution.

  4. Fill in your app’s name and the app identifier. The wizard provides defaults, but you might want to align the app identifier to use your company’s reversed URL, or change the app name in some other way:

    Wizard App Details
  5. Click Next Step when ready.

  6. In the Build type choose the Advanced checkbox.

    Build type

  7. Select the folder for your app’s Native Template. Valid choices are an empty directory or a directory with an existing Native Template.

  8. Disable any service you do not wish to use. App Center requires GitHub as a service to work.

  9. Click Next Step until you reach the end of the wizard. Feel free to configure any step as needed.

  10. Select Build type from the side bar.

    Build type

    As you already selected to use the Advanced flow with this app it is not possible to switch back to just using Cloud services. But you can enable or disable any service as needed. If for instance GitHub is enabled, Native Mobile Builder will synchronize any local changes with your repository the next time you configure your app and commit your changes. But keep in mind that the Mendix Native Builder is not a replacement of a Git client, and pushing local changes to a repository can add to the configuration time.

  11. Select Configure app locally and fill in the information as needed for your app.

    Build type

  12. Click Configure locally

    The process will start and it will:

    • Derive the required native dependencies for your app based on the pluggable widgets used in your app
    • Run MxBuild to build your app bundles
    • Checkout the correct version of Native Template for the Mendix Studio Pro version you are using
    • Configure the app

    If GitHub is enabled, in addition to the previous steps, it will: * Commit the whole local copy to the app’s repository

4 Building your Native Mobile App

Now that the Native Template is ready and includes the app’s bundle, resources, and runtime URL configuration, it can be built into a native app. To build your app you can open the app with Android Studio or XCode for the Android and iOS app respectively, and then build as normal. More advanced use cases, such as apps for continuous integration pipelines, can make use of Gradle or xcodebuild to build the apps using command line.

In the sections below you can see the basic steps to get an app up and running on an emulator or device using Android or iOS IDEs.

4.1 Building an Android App with Android Studio

  1. Run npm install in the app root to install the required dependencies.
  2. Open Android Studio.
  3. Select the <Native Template root>/android as the entry point for the app.
  4. After synchronizing the app your Android Studio should look something like this. Do not accept any suggestions to update to latest Gradle or Kotlin version:

    Android Studio

Mendix native mobile apps make use of Build Variants to build a release app or a custom developer app. The idea of Build Variants is a Gradle build system concept for sharing the same codebase but delivering different experiences.

  1. Choose the appstoreDebug variant to be able to build and test your app on an emulator or connected device:

    Android Build Varients
  2. After a short time the app should be synchronized and the play button (Run Locally) should be selectable. Select a device or create a device from the drop-down menu and click the play button (Run Locally) to build and install your app on the device:

    Android Build Toolbar

4.2 Building an iOS App with XCode

  1. If you have not ran it yet, run npm install in the app root to install the required dependencies.
  2. Change directory by running cd ios and run pod install to install the iOS dependencies.

    The iOS app is using CocoaPods for its dependency management. For more information on installing the CocoaPods dependency manager on your machine see CocoaPods documentation.

  3. Open .xcodeworkspace using XCode.

  4. Navigate to Signing and Capabilities and choose your Team from the drop-down menu:

    XCode Build Toolbar

    As with the Android Build Variants the iOS app makes use of Build Targets to switch between building a custom developer app or a release app.

  5. From the drop-down menu choose nativeTemplate and the device you would like to run the app on, then click the play button (Run Locally) to start a build for your app:

    XCode Build Toolbar

After the build succeeds the app should be running on the selected device and connected to the runtime using the runtime URL you provided.

5 Adding Dependencies

Mendix Studio Pro 9 and later support a new format for widgets and JS actions, allowing them to define them Native Dependencies required. Mendix Native Mobile Builder, is able to derive the Native Dependencies required from the app and automatically adds them to the package.json of the app’s Native Template. This works with all auto-linkable Native Dependencies.

In some cases though, like when a dependency isn’t derivable by its use case, like from a widget or JS action, or the dependency requires extra additions, like an elaborated initialisation process that can’t be described via the auto-linking protocol, you will have to modify your app and add it manually.

Mendix native mobile apps are build on top of React Native. Therefore, any React Native module can be added and used in an app. The same rules apply as with any React Native app.

5.1 Adding Dependencies Which Support Auto-Linking

Mendix supports RN and therefore auto-linking. Auto linking is a React Native mechanism that allows React Native to link the native dependencies defined in the package.json file automatically with the native apps. To add dependencies do the following:

  1. Add the dependency to the root package.json of your Native Template using npm i -s <dependency name>.
  2. If the dependency supports auto-linking when npm install is run it will automatically add itself correctly to the Android and iOS apps. If the dependency does not support auto-linking or requires more configuration, follow its documentation to add the required entries manually.

5.2 Adding Dependencies Which Do Not Support Auto-Linking

If a dependency does not suport auto-linking follow the steps of the dependency’s documentation to add it to the Android and iOS apps.

6 Removing Dependencies

As the requirements of an app might change, so do the required native modules and libraries. To avoid bloating your app with unnecessary libraries, consider removing unused libraries. This process is not currently automated and requires a bit of consideration when identifying any unused libraries.

6.1 Removing Dependencies Which Support Auto-Linking

To remove dependencies which support auto-linking, do the following:

  1. Remove the dependency entry from the package.json file.
  2. Run npm i.

6.2 Removing Dependencies Which Do Not Support Auto-Linking

To remove dependencies which do not support auto-linking, revert the steps you applied when adding the dependency.

7 Read More