Build a Mendix Hybrid App Locally

Introduction

This document describes how to build your hybrid apps locally.

Building Your iOS App Locally

Prerequisites:

• A Mac OSX machine
• Install Node.js 18 using the all-in-one installation option
• Download your local build package from Cloud Portal and unzip it in a known location
• Register for an Apple Developer Account
• Install Xcode and its command-line tools

Prepare Your App for Building

To prepare your app for building, follow these instructions:

1. Open a terminal window and change directory into the unzipped package folder, for example cd /Downloads/localbuild if it is in your Downloads folder.
2. Run npm i && npm run package && npm run platform:ios. This combination of commands does the following:
   • Installs all required dependencies.
   • Packages the Cordova app for deployment.
   • Adds the iOS platform to Cordova.

Customizing a DTAP Endpoint

Optionally, you can set various environments in the config/environments.json file. This can help if you are trying to make your build from your own specific test or acceptance environment.

To target a specific DTAP endpoint with your app, you can specify it as a parameter to npm run package or npm run package:x86. Such code could, for example, look like this:

npm run package -- --env target=test  # target the test endpoint for ARM architecture

Possible targets are development, test, acceptance, production (default), and sandbox. For convenience you can shorten these to their first letters. Note that if no --env target parameter is provided, the hybrid app endpoint will default to the production environment.

Building Your Prepared Project

There are two possible ways to build your apps: the Cordova CLI or Xcode. The Cordova CLI is faster and allows Cordova to fully control the your app’s configuration. Xcode is more involved, but Xcode’s UI makes it easier to detect problems in the app. You can use whichever works best for your case.

Building iOS Using the Cordova CLI

Prerequisites:

• Your Apple Developer team’s id, which can be found here

This process is shorter than using Xcode but might require more work to understand why a build fails. To build using the Cordova CLI, do the following:

1. Run npm run build -- ios --release --device --codeSignIdentity="iPhone Developer" --developmentTeam="<your-teams-id>". This combination of commands does the following:

   • Starts a release build that will create binaries for a physical device
   • Uses the code sign identity “iPhone Developer” for signing
   • Looks up the provisioning files and certificates using the provided Apple Developer’s team id
   • Optionally, if you wish to build for an emulator and do a debug build use the following command instead: npm run build -- ios --debug --emulator.

2. When the build succeeds the generated IPA file can be found in /build/platforms/ios/build. That folder should have the following file structure(if you did a build for an emulator an .app file will be available):

   

3. The IPA generated can be now uploaded to Testflight for further testing. If you wish to do so, continue with the Upload tools section in the Apple App Store documentation.

Building iOS using Xcode

Using Xcode can be easier than the Cordova CLI due to Xcode’s friendly visual interface. To build your app using Xcode do the following:

1. Under /build/platforms/ios/ open the .xcworkspace file by double-clicking it. Xcode should open with the app loaded:

   

2. Select the root element from the tree view in the left-side panel:

   

3. The screen should change to the following view. If it does not, select the item under Targets on the left panel not the item under App and select the tab Signing & Certificates:

   

4. Both Debug and Release might have been configured for Automatically manage signing. Clear both checkboxes to switch to manual signing. The screen should change to the following:

   

5. Enable Automatically manage signing again.

6. Select a Team using the drop-down menu. If you have not yet signed in with your credentials, Xcode will prompt you to do so.

7. When configured correctly all errors should be gone.

8. Make sure you select the target to be your app’s build target and designate Generic iOS Device as a device:

   

9. Select Product and then Archive from the menu bar:

   

10. After the process finishes successfully the Organizer view will come up. Your app should be selected and your latest Archive visible. You can always open the organizer yourself through Xcode’s Window menu:

    

11. You can now use the Distribute App button to distribute your app to the appstore or archive it for local distribution:

    

Building Your Android App Locally

Prerequisites:

• Install AndroidStudio
• Install Node.js 18 using the all-in-one installation option
• Install JDK 1.8
• Create a keystore using Generating a Keystore
• Download the local build package from Cloud Portal and unzip it in a known location

Prepare Your App for Building

To prepare your app for building, follow these instructions:

1. Open a terminal window and change directory into the unzipped package folder, for example cd /Downloads/localbuild if it is in your Downloads folder.
2. Run npm i && npm run package && npm run platform:android. This combination of commands does the following:
   • Installs all required dependencies
   • Packages the Cordova app for deployment
   • Adds the Android platform to Cordova

Set Up Environmental Variables

To be able to run the commands to build locally, you will need to set up some required environmental variables for your system. These can be set to temporary for the current command line session or globally for your system. The variables are the following:

• ANDROID_SDK_ROOT, pointing to the installation folder of the Android SDK
• JAVA_HOME, pointing to the JDK 1.8 root directory
• GRADLE_HOME, pointing to a valid Gradle distribution directory

During this guide you will set the commands to temporary for each of the commands.

Building Your Prepared Project

There are two possible ways to build your apps: the Cordova CLI or Android Studio. The Cordova CLI is faster and allows Cordova to fully control the your app’s configuration. Android Studio is more involved, but Android Studio’s UI makes it easier to detect problems in the app. You can use whichever works best for your case.

Building Android Using the Cordova CLI

The command to build your app locally for release is npm run build -- android --release.

1. Run the following command:

   1. On Mac OSX, as a single command run:
      

      PATH="\$PATH:/Users/<username>/.gradle/wrapper/dists/gradle-5.1.1-all/97z1ksx6lirer3kbvdnh7jtjg/gradle-5.1.1/bin" JAVA_HOME=`/usr/libexec/java_home -v 1.8\` npm run build -- android --release -- --keystore=<keystore-path> --storePassword=<keystore-password> --alias=<keystore-alias> --password=<certificate-password>
      

   2. On Windows, in a command line as separate commands run:
      

      set PATH=%PATH%;C:\path-to-gradle-distribution
      
      set JAVA_HOME=C:\path-to-jdk-1.8-directory
      
      npm run build -- android --release -- --keystore=<keystore-path> --storePassword=<keystore-password> --alias=<keystore-alias> --password=<certificate-password>
      

   This command adds the gradle binary to the path, switches the JAVA JDK to be 1.8, and runs the build release command to generate a signed APK.

2. When the build succeeds the generated APK file can be found in /build/platform/android/app/release:

   

Building Android Using Android Studio

Using Android Studio can be easier than the Cordova CLI due to Android Studio’s friendly visual interface. To build your app using Android Studio do the following:

1. Start Android Studio:

   

2. Open an existing Android Studio project and select your app’s Android folder, for example /Downloads/localbuild/build/platform/android:

   

3. Wait for Android Studio to finish syncing your app.

4. Click the Build > Generate Signed Bundle / APK:

   

5. Select the APK checkbox:

   

6. Select your Android keystore and complete the form with the correct keystore password, alias, and password:

   

7. Select the destination folder for the APK, Build Variant release, and V1 and V2 Signature versions:

   

8. Click Finish.

You APK should now be generated and signed using Android Studio. The resulting APK can be found in the output folder selected and can be uploaded via the Google Play Console for further processing.

Read More

• Deploying Apps
• Offline Reference Guide
• How to Publish a Mendix Hybrid Mobile App in App Stores
• Apache Cordova Reference Config.xml