Build a standalone app

If your deployment pattern does not allow a map.apps backend installation, you can create standalone apps, which can be deployed to a web server directly. If the dynamics of the map.apps backend and management via the map.apps Manager can be omitted, this approach can also help to achieve better performance and simpler deployment.

This guide explains how to create a standalone app using the standaloneApp goal of the mapapps-maven-plugin. This goal creates an export similar to the one generated when using the Export for Native App button in /manager.

This goal was introduced in version 4.19.2.

Checklist

To follow this guide, you need:

  • a map.apps project based on map.apps for Developers, version 4.19.2 or higher.

  • This build is only supported if all javascript assets are available as direct project dependencies. It will not work if mapapps-4-developers is configured against a map.apps remote installation.

Step 1: Run the standalone build

To create a standalone app, execute the following command in the project root folder:

mvn clean package -P compress,standalone

The compress profile must be enabled, as it ensures compressed assets and generates the required dependencies.json files for the project bundles. After the build has finished, you can find the standalone app in the target/export/<app-name> folder.

Step 2: Test the standalone app

To test if the standalone app works, you can deploy it to a web server. If you have node installed, you can use the following command to start a simple web server:

cd target/export/<app-name>
npx serve .

This will run a webserver on port 3000 and you can access the standalone app in your browser at http://localhost:3000.

You can customize the standalone app export, by modifying the profile standalone in the pom.xml of your project. For more information about the available configuration options, see mapapps-maven-plugin.

Step 3: Deploy the standalone app

You can now take your standalone app from the folder target/export/<app-name> and deploy it to your desired web server.

Common problems and solutions

Missing properties

Problem

When building a standalone app, you might encounter the following warning:

[WARNING] Please check if these properties are configured in the app:
 themes.default.theme
 geometry.service.url
 bingmaps.api.key

Solution

This warning is shown if @@key@@ expressions are detected without a matching value.

This warning does not mean that it has to be fixed. Maybe the missing key is already overwritten by a bundle specific setting in the app.json or never used.

If a value is required, add the missing key to the replacementProperties configuration of the standaloneApp goal in the pom.xml as in the following sample:

<replacementProperties>
  <geometry.service.url>https://www.example.com/my-geometry-service</geometry.service.url>
</replacementProperties>

Alternatively you can add the missing key into the file src/test/resources/application.properties. This has the advantage that you can use the properties both in your dev environment and the standalone export.

Too many file requests

Problem

The exported app loads a large number of individual esri/* files during startup, which can slow down performance.

Solution

Add the map-preload-2D or map-preload-3D bundle to your app.json allowedBundles section. Alternatively, you can configure these bundles using the exportCustomModules option in the standaloneApp goal in the pom.xml file.

Missing bundles

Problem

Some bundles are missing in the exported app after building.

Solution

First check the allowedBundles configuration in the app.json. The bundles listed in the allowedBundles section are located at the projects classpath or at the target/webapp/js/bundles folder.

To add a bundle to the projects classpath you need to specify a dependency in the pom.xml of your project. For example, to add the mapapps-query-builder bundle you need to add the following dependency:

<dependencies>
    ...
    <dependency>
        <groupId>de.conterra.devnet</groupId>
        <artifactId>mapapps-query-builder</artifactId>
        <version>5.3.4</version>
    </dependency>
</dependencies>