Theme extensions

map.apps allows you to create a bundle that extends an existing theme. This can be helpful in multiple circumstances:

  • You want to use a map.apps default theme but your custom bundles require custom styling.

  • You develop a custom main theme but your bundles are developed separately.

Although it is possible to provide custom CSS with each bundle, it makes sense to package all needed styles for a set of bundles in a themes extension bundle for the following reasons:

  • Less CSS is easier to use.

  • Files are compressed and packed into a single file during the build process. This results in fewer server requests in production.

The purpose of a theme extension is not to customize the overall look and feel of map.apps but to provide compulsory style declarations for custom bundles.

The setup consists of a few steps which are described below and require map.apps for Developers as base project.

Creating a theme extension for a single theme

In the following guide we’ll provide additional styles for two fictional bundles called earth-shadow-viewer and map-locate. The theme extension will extend the map.apps default theme everlasting.

Step 1: Scaffolding the bundle

Create a folder called src/main/js/bundles/custom-theme-extension with a manifest.json and the following content inside:

    "name": "custom-theme-extension",
    "version": "1.0.0",
    "description": "This bundle provides additional styling rules, applied when the active theme is everlasting",
    "i18n": [],
    "layer": "",
    "main": "",
    "startLevel": 1,
    "cssThemesExtension": [
            "name": "everlasting"

Create the following files at the given locations with the displayed content:

@import url("styles/bundles/bundles.css");
@import url("earth-shadow-viewer.css");
@import url("map-locate.css");
@import "../themeSettings.less";
.@{themeName} {
  /*additional styling for custom bundle can be placed here*/
@import "../themeSettings.less";
.@{themeName} {
/*additional styling for custom bundle can be placed here*/

Delete the folder theme-custom from src/main/js/bundles as it is not possible to develop a custom theme and a theme extension in the same map.apps project.

Step 2: Configuring the gulpfile

Open gulpfile.js inside the project’s root folder and replace the complete call of mapapps.registerTasks(…​) with the following:

    /* A detailed description of available settings is available at */
    themes: ['everlasting'],
    themesSrcLocation: "./src/main/js/bundles/custom-theme-extension",
    themesDestLocation: "./target/webapp/js/bundles/custom-theme-extension"

Step 3: Adjusting the pom.xml

To use Less variables from the base theme (e.g. the @themeName or colors) you must copy the theme’s themeSettings.less file before compiling. Add the following <resources> element to the pom.xml inside the project’s root folder.

    <!-- Add this element: -->
        <!-- Copy Theme Resources -->

You must also change the execution phase of the frontend-maven-plugin to process-resources:

    <id>run gulp ${gulp.task}</id>
    <!-- add this element: -->

After that, everything is set up and the development server can be started as usual.

Step 4: Testing the setup

To test your setup add the custom-theme-extension bundle from step 1 to the app.json of src/main/js/apps/ and load the app inside the browser. Use the browser’s developer tools to check that the files map-locate.css and earth-shadow-viewer.css get loaded.