Compiling a bundle with Rollup

map.apps projects that use ct-mapapps-gulp-js to build the project (like map.apps for Developers does) can enable the JavaScript module bundler Rollup to compile the code of a bundle. The benefits are:

  • Reduced amount of output files.

  • Optimized code and thus reduced size of bundles.

  • Ability to control which files of a bundle can be imported by other bundles.

This guide explains how to compile bundles of your map.apps project with Rollup.

Checklist

To follow this guide, you need:

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

Step 1: Enable Rollup compilation for a bundle

Before you start to enable Rollup in any bundle, first set your project to a clean state:

  1. Stop the development server if it is running.

  2. Clean the build folder by running mvn clean in the project root folder.

To enable a Rollup build for a bundle, follow the steps below. You need to execute the steps for each bundle that should be compiled with Rollup.

  1. Make sure the development server is stopped.

  2. Create a new file called build.config.js in your bundle’s root directory, next to your manifest.json, with the following content:

    module.exports = {
        type: "bundle",
        entryPoints: ["./module"] //module.js is the only entry point here
    };

    List all JavaScript files in the entryPoints array that must be available from outside of your bundle, for example because they’re used by the App Runtime (e.g. module.js) or because they’re imported by other bundles at runtime. Internal files should not be listed, they will be detected and bundled automatically by Rollup.

  3. Replace all imports of dojo/text!<file> using text! instead:

    // before:
    import textContent from "dojo/text!./templates/myTemplate.html";
    
    // after:
    import textContent from "text!./templates/myTemplate.html";

    The path must be a relative path to a file in the current bundle.

Step 2: Examine the build output

When you start the development server, the bundles will be compiled. When the build is ready, the output for a bundle will look like this:

target/webapp/js/bundles/<bundle>/
dependencies.json
manifest.json
module.js
module.js.map

Alongside the manifest.json you find the new file dependencies.json as well as a compiled .js and .js.map file for every entry point you defined in build.config.js.

Hints

Solving build errors "ERROR [bundles\mybundle] [plugin commonjs—​resolver] Cannot import…​"

When using Rollup to compile bundles, you may encounter errors due to unresolvable imports like this:

[11:24:04] >C:\dev\mapapps-4-developers\src\main\js\bundles\mybundle\mymodule.js
[INFO] [11:24:04] >...lint using ESLint
[INFO] [11:24:04] >...rollup C:/dev/mapapps-4-developers/src/main/js/bundles/mybundle
[INFO] 1 file linted
[INFO] [11:24:04] ERROR [bundles\mybundle] [plugin commonjs--resolver] Cannot import 'apprt-core/string-replace' from 'src\main\js\bundles\mybundle\mymodule.js': bundle 'apprt-core' must be listed as a dependency.
[INFO] [11:24:04] ERROR [bundles\mybundle] Failed to build
[INFO] [11:24:04] <finished

This is caused by missing dependencies entries in the bundle manifest. To solve the error of the previous example, we have to add apprt-core as a dependency like this:

mybundle/manifest.json
{
    "name": "mybundle",
    "version": "1.0.0",
    "i18n": [],
    "dependencies": {
        "apprt-core": "^4.15.0"
    },
    "components": [
        ...
    ]
}

Obsolete "calculateDependencies" execution

If all bundles in your project are configured to use Rollup, you can remove the calculateDependencies plugin execution from the pom.xml file.