Bundling HERE Maps API for JavaScript

This section shows how to bundle the HERE Maps API for JavaScript with the help of several most common bundlers such as Webpack and Rollup. The sections below provide the simple boilerplate code that produces the output for the bundler of choice.

Getting started

In order to be able to use the HERE Maps API for JavaScript with NPM the HERE public repository must be added to the NPM configuration:

npm config set @here:registry https://repo.platform.here.com/artifactory/api/npm/maps-api-for-javascript/

1. Assuming that the node.js and npm are installed create a directory that will contain the project and run from the console the following command:

   npm init
   

   It will produce the package.json file similar to the one below:

   {
   "name": "bundling-test",
   "version": "1.0.0",
   "description": "",
   "main": "index.js",
   "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
   },
   "author": "",
   "license": "ISC"
   }
   

2. Add a dependency to the HERE Maps API for JavaScript library:

   npm install @here/maps-api-for-javascript --save
   

Rollup

1. Add developement dependencies to Rollup and a Rollup module resolution plugin to the project:

   npm install rollup @rollup/plugin-node-resolve --save-dev
   

2. Create Rollup configuraion file rollup.config.js in the root directory of the project with the following configuration:

    import resolve from '@rollup/plugin-node-resolve';
   
    export default {
    input: 'index.js',
    output: {
        dir: './out/',
        format: 'iife'
    },
    // Disable "Use of Eval" Warning
    // The HERE Maps API for JavaScript uses 'eval' to evaluate
    // filter functions in the YAML Configuration for the Vector Tiles
    onwarn: function (message) {
        if (/mapsjs.bundle.js/.test(message) && /Use of eval/.test(message)) return;
        console.error(message);
    },
    plugins: [resolve()]
    };
   

   The configuration above defines the input source and output directory for the bundled script, as well as the format of the output.

3. The Rollup was installed locally - update the script section of the package.json by adding the bundletarget:

   "bundle": "rollup --config rollup.config.js"
   

4. Create an index.js file that is the entry point for Rollup:

   
    import H from '@here/maps-api-for-javascript/bin/mapsjs.bundle';
   
    // Initialize the platform object:
    var platform = new H.service.Platform({
    'apikey': '{YOUR_API_KEY}'
    });
   
    // Obtain the default map types from the platform object
    var maptypes = platform.createDefaultLayers();
   
    // Instantiate (and display) a map object:
    var map = new H.Map(
    document.getElementById('mapContainer'),
    maptypes.vector.normal.map,
    {
        zoom: 10,
        center: { lng: 13.4, lat: 52.51 }
    });
   

   The code above repeats the steps from the Get Started chapter.

Webpack

1. Add development dependencies to the Webpack

   npm install webpack webpack-cli  --save-dev
   

2. Create Webpack configuration file in the root directory of the project with the following configuration:

    const path = require('path');
    const TerserPlugin = require('terser-webpack-plugin');
   
    module.exports = {
    mode: 'production',
    entry: {
        index: './index.js'
    },
    output: {
        publicPath: './out/',
        path: path.resolve(__dirname, 'out'),
        filename: '[name].js',
        chunkFilename: '[name].bundle.js'
    },
    optimization: {
        minimizer: [new TerserPlugin({
        chunkFilter: (chunk) => {
            // Exclude mapsjs chunk from the minification as it is already minified
            if (/mapsjs/.test(chunk.name)) return false;
            return true;
        }
        })],
    }
    };
   

   In the configuration above the mapsjs.bundle.js is explicitly excluded from the minification process. That is done in order to prevent adverse effects of the double minification. The entry module itself lazy-loads the HERE Maps API for JavaScript in order to take advantage of the Webpack's code splitting.

3. Webpack was installed locally - update the script section of the package.json by adding the bundletarget:

   "bundle": "webpack"
   

4. Create an index.js file that is the entry point for the bundler:

    import(/* webpackChunkName: "mapsjs" */ '@here/maps-api-for-javascript/bin/mapsjs.bundle').then(
    ({ default: H }) => {
        var platform = new H.service.Platform({
        'apikey': '{YOUR_API_KEY}'
        });
   
        // Obtain the default map types from the platform object
        var maptypes = platform.createDefaultLayers();
   
        // Instantiate (and display) a map object:
        var map = new H.Map(
        document.getElementById('mapContainer'),
        maptypes.vector.normal.map,
        {
            zoom: 10,
            center: { lng: 13.4, lat: 52.51 }
        });
    }
    ).catch(error => console.log(error));
   

   The code above makes use of the dynamic imports which is the recommended way of the dynamic code splitting for the Webpack. The body of the function remains without changes.

Running the bundler

1. In the root directory of the project create an index.html file that will be an entry point for the application:

    <html>
    <head>
        <meta name="viewport" content="initial-scale=1.0, width=device-width" />
        <style>
        #map {
            position: absolute;
            left: 0;
            top: 0;
            width: 100%;
            height: 100%;
        }
        </style>
    </head>
    <body>
        <div id="mapContainer"></div>
        <script src="./out/index.js"></script>
    </body>
    </html>
   

2. Run the following command from the console.

   npm run bundle
   

   It will produce the bundled build and will put it in the out directory. Accessing the index.html page from the browser will display the following result: