Build a standalone app

If your deployment pattern does not allow a map.apps backend installation, you can create standalone apps. A standalone app is a directory of files that contains all required resources and assets for that app. It does not need the map.apps backend service to run. Instead you can just copy the standalone app’s directory to a web server.

Standalone app don’t benefit from the the dynamics of the map.apps backend or app management features of the map.apps Manager. Their main advantages are better performance and simpler deployment.

In this how-to…​
This guide demonstrates how to convert a map.apps app into a directory of files and serve the app with a simple web server.

This guide is making use of the standaloneApp goal of the mapapps-maven-plugin. This plugin goal creates an export similar to the one generated when using the "Export for Native App" button in the map.apps Manager.

Checklist

To follow this guide, you need:

  • A project based on map.apps for Developers with:

    • map.apps version 4.19.2 or higher

    • all JavaScript assets available as direct project dependencies

    • non-remote mode setup

  • Node installed to be able to run npx commands.

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 command enables the compress profile to compress all assets and generate 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, deploy it to a web server following these steps:

  1. Execute the following commands in the project root folder:

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

    This will run a webserver on port 3000 to serve the resources from target/export/<app-name>/

  2. In a web browser, open the URL http://localhost:3000 to run the standalone app.

Step 3: Deploy the standalone app

To deploy the standalone app, copy the folder target/export/<app-name> to your desired web server.

Next steps

  • 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.

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 to 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 @arcgis/core/* files during startup, which can slow down performance.

Solution

Add the map-preload-2D or map-preload-3D bundle to the allowedBundles section in your app.json. 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>