PWA Wrapper (Beta)

Content Type: Module
Categories: Extensions,Mobile

Overview

About

PWA Wrapper packages a Mendix PWA into native Android and iOS app artifacts. It gathers app resources, applies wrapper settings, and produces outputs you can use for testing, signing, and distribution.

 

What It Produces

  • Android APK for device installation and Android distribution flows
  • iOS IPA for physical-device testing or distribution on macOS
  • iOS simulator artifacts when available during macOS builds
  • Portable iOS signing packages on Windows for final signing on a Mac

 

Platform Notes

  • Android builds can be installed on a connected device or emulator after packaging
  • iOS final signing and device builds require macOS
  • Windows can prepare the iOS bundle, but not complete the final signed IPA
  • Only enable permissions and capabilities your app actually uses

Testing Guidance

  • Use emulators and simulators for quick validation where possible
  • Test hardware-dependent features on real devices before release
  • iOS physical-device testing requires a signed IPA
  • Some web API-backed capabilities require a secure context

Next Step

After packaging, continue with the platform-specific signing or distribution flow for your app.

 

Documentation

Introduction

Use PWA Wrapper to generate Android and iOS packages from a Mendix PWA. The builder collects your app resources, applies wrapper configuration, and produces platform-specific build artifacts such as APK and IPA files.

Before following this guide, make sure you have completed Install PWA Wrapper.

Build an Android APK

Prerequisites

No separate Android packaging prerequisites are required before you start the Android build flow in PWA Wrapper.

Install Android Studio only if you want to use Android emulators for testing.

Steps

To generate an Android APK, do the following:

  1. Open the builder and select Android.
  2. In the app information step, enter the app metadata:
    • app name
    • app version
    • Android package name in reverse-domain format such as com.example.myapp
    • app icon
    • runtime URL of the Mendix app

{{< figure src="/attachments/refguide/mobile/pwa-wrapper/app-information.png" alt="Android app information step in the PWA Wrapper builder" width="350" class="no-border" >}}

  1. Review the available permissions and enable only the permissions needed by the capabilities your app uses. For capability-to-permission guidance, see Capability to Permission Mapping.

{{< figure src="/attachments/refguide/mobile/pwa-wrapper/permissions.png" alt="Permissions step in the PWA Wrapper builder" width="350" class="no-border" >}}

  1. Go to the signing step and do one of the following:
    • choose an existing Android signing configuration
    • create a new signing configuration if this is the first Android build for the app; for platform-specific details, see Sign Android Apps on Windows and macOS
  2. Continue to the packaging step and start package generation.

{{< figure src="/attachments/refguide/mobile/pwa-wrapper/package-android-app.png" alt="Packaging step for building an Android APK with PWA Wrapper" width="350" class="no-border" >}}

  1. Wait for the build to complete.
  2. Open the output directory from the builder.
  3. Retrieve the generated APK.
  4. If you want to test immediately, continue to the optional installation step and install the APK on a connected Android device.

Signing Notes

The signing step is part of the Android build flow. The selected signing configuration determines how the APK can be used:

  • Unsigned packages are suitable only for limited testing scenarios such as emulators
  • Signed packages are required for device installation and normal distribution workflows

For platform-specific details about the signing step, see Sign Android Apps on Windows and macOS.

Android Output

The builder generates an Android APK that you can install on a connected device or submit to your standard Android distribution pipeline.

If you use the installation step in the builder, keep the following in mind:

  • Connect the Android device before starting installation
  • Unlock the device and allow debugging or installation prompts if requested
  • If a newer build of the same app is already installed with incompatible signing or versioning, uninstall it first

Build an iOS Package

Prerequisites

For iOS packaging, install or prepare the following:

  • Xcode or Xcode Command Line Tools to bundle and sign the iOS app on macOS
  • Apple signing assets, including a .p12 certificate and a .mobileprovision profile, if you want to build for a physical device or distribute the app
  • A bundle identifier that matches the Apple signing configuration, if you want to build for a physical device or distribute the app

Install full Xcode if you want to use the iOS simulator for testing.

{{% alert color="warning" %}} iOS packaging for a final signed device build requires macOS. On Windows, you can prepare the portable signing package, but you still need a Mac to generate the final signed IPA. {{% /alert %}}

Steps on macOS

To generate a signed iOS package on macOS, do the following:

  1. Open the builder and select iOS.
  2. In the app information step, enter the app metadata:
    • app name
    • app version
    • iOS bundle identifier in reverse-domain format such as com.example.myapp
    • app icon
    • supported device type if the builder asks for it
    • runtime URL of the Mendix app
  3. Review the permissions and enable only the permissions required by your app. For capability-to-permission guidance, see Capability to Permission Mapping.
  4. Go to the signing step and create or select an iOS signing configuration. For platform-specific details, see Sign iOS Apps on macOS.
  5. Continue to the packaging step and start package generation.

{{< figure src="/attachments/refguide/mobile/pwa-wrapper/package-ios-app.png" alt="Packaging step for building an iOS package with PWA Wrapper" width="350" class="no-border" >}}

  1. Wait for the build to complete.
  2. Open the output directory and retrieve the generated artifacts.
  3. Use the signed .ipa for physical-device testing or distribution when a valid signing configuration is provided.
  4. Use the .app artifact for simulator testing when it is available.
  5. If you are testing on macOS, optionally continue to the installation step to install the generated app on a simulator or connected device.

Steps on Windows

On Windows, PWA Wrapper can prepare the iOS bundle but not complete the final signing step. The builder produces a portable signing package that can be moved to a Mac.

On Windows, use the same steps 1 through 7 as in Steps on macOS, then continue as follows:

  1. Open the output folder and locate the portable signing ZIP.
  2. Copy the portable signing ZIP to a Mac.
  3. Complete the final signing step on macOS as described in Complete Signing on macOS.

iOS Notes

Keep the following limitations in mind:

  • Physical iOS devices require a signed IPA
  • The builder installation step for iOS is available only on macOS hosts
  • Copying packaged web resources is currently not supported on iOS, so the wrapped app must load its frontend resources from the deployed Mendix runtime

For platform-specific details about the signing step inside this build flow, see Sign iOS Apps on macOS for macOS builds and Prepare iOS Apps on Windows for Windows builds.

Choosing Permissions and Packaging Options

When configuring the wrapper, only enable the permissions and capabilities that your app actually uses. This reduces unnecessary prompts for end users and makes app review easier.

For a practical mapping between capabilities and the permissions you typically need to configure, see Capability to Permission Mapping.

If the builder offers a choice to skip copying web resources, use that option carefully. Skipping resource copy makes packaging faster, but the wrapped app will fetch its frontend resources from the runtime instead of using packaged resources.

Optional Installation Step

After packaging, the builder can help you install the generated app in supported scenarios.

For Android:

  1. Connect the Android device or start the emulator.
  2. Select the target device in the builder.
  3. Start installation.
  4. Open the app from the device launcher after installation completes.

{{< figure src="/attachments/refguide/mobile/pwa-wrapper/run-on-android-emulator.png" alt="Install the generated Android app on an emulator from the PWA Wrapper builder" width="350" class="no-border" >}}

For iOS on macOS:

  1. Connect the iOS device or start the iOS simulator.
  2. Make sure you generated the correct artifact:
    • .ipa for a physical device
    • .app for the simulator
  3. Select the target device in the builder.
  4. Start installation.
  5. Launch the app from the device or simulator after installation completes.

{{< figure src="/attachments/refguide/mobile/pwa-wrapper/run-on-ios-simulator.png" alt="Install the generated iOS app on a simulator from the PWA Wrapper builder" width="350" class="no-border" >}}

If installation fails, check the builder error message first. Common causes are missing signing, incompatible provisioning, unavailable devices, or an already installed newer build.

Testing Limitations

Keep the following testing limitations in mind while validating a wrapped app:

  • Hardware-dependent capabilities often require a physical device for realistic testing
  • Barcode and QR scanning, camera capture, geolocation, and biometric authentication should be validated on physical devices
  • Features such as network information, file download, URL opening, printing, sharing, local notifications, and permission flows can be tested first on simulators and emulators, but final verification should still happen on real devices
  • Web API-backed capabilities such as network information, Share API flows, geolocation, notifications, and permission handling require a secure context. For more information, see Secure Context
  • iOS physical-device testing requires a signed IPA
  • Capability behavior can differ between test devices even within the same platform

If your app depends on device hardware, validate the final packaged app on representative Android and iOS devices before release.

Next Steps

After building the wrapper app, continue with the appropriate distribution process for your target platform.

If you still need platform-specific details for the signing step in the build flow, see Sign Android Apps on Windows and macOS, Sign iOS Apps on macOS, or Prepare iOS Apps on Windows.

To understand which capabilities you can use from your Mendix app, see PWA Wrapper Capabilities.

 

 

 

 

 

 

 

 

 

 

Releases