A lighter, faster Mapbox GL JS with a new modular architecture

Mapbox GL JS now includes a new High Definition (HD) ‘module,’ part of a multi-phase effort to enhance the GL JS architecture with advanced rendering capabilities without slowing down performance. Rather than shipping HD features with all other rendering capabilities in a single bundle, modularized HD features only load when needed.

For most developers, GL JS modularization means significantly less JavaScript downloaded immediately, resulting in a smaller bundle size and faster initial page loads.

Ship faster maps with a smaller JavaScript bundle

One of the most common requests from the GL JS developer community has been a smaller JavaScript bundle. Previously, Mapbox GL JS shipped as a single library containing every rendering capability available on the platform. Developers building data visualizations or location experiences like store locators, dashboards, or low-zoom maps where 3D/HD detail is not visible had to download the full library with advanced features even if those capabilities never appeared in the application.

As GL JS evolved to support increasingly detailed map features, the size of the core library naturally grew. Modularization means that advanced features will no longer increase JavaScript bundles, download and parse times, and bandwidth usage for those that don’t need advanced features.

A new modular architecture for Mapbox GL JS

With GL JS modularization, advanced rendering features are separated into optional modules. The HD module is the first module released and it includes:

• HD road details
• Elevated line rendering
• Enhanced building facade details
• Indoor airport maps
• Rain and snow rendering effects
• 3D landmark models

Now when a GL JS application uses the Mapbox Standard Style, only the core rendering engine is downloaded by default. If a developer delineates the style to include the HD module, it loads automatically in the background with no additional configuration required. The result is a faster default experience while preserving access to advanced rendering capabilities.

A faster GL JS from startup to interaction

The new modular architecture allows GL JS to load advanced rendering features only when actually required. Developers who do not need the HD module benefit from a 10–15% reduction in JavaScript bundle size, helping applications start faster while reducing unnecessary network and CPU work.

The new modular architecture builds on a series of rendering engine optimizations introduced in GL JS v3.24 which systematically improved resource allocation, thread efficiency, and asset compilation. Together, the foundational performance improvements and new modular architecture create a faster, more efficient rendering engine that scales even as Mapbox adds new capabilities.

Time-to-idle is reduced by up to 50%, cutting in half the time it takes for a map to become fully stable, visually complete, and interactive.

CPU and memory utilization has been reduced across client devices, leading to lower battery consumption and better performance on lower-spec hardware.

How to enable the new modular architecture

To opt in to the new modular architecture, update to GL-JS v3.25 or later. Then switch from the UMD bundle to the ESM entry point.

For NPM users

Change existing imports to use the ESM entrypoint and provide an access token directly when instantiating the map:

import * as mapboxgl from 'mapbox-gl/esm';
const map = new mapboxgl.Map({
    accessToken: <ACCESS_TOKEN>,
    container: 'map'...
});

‍

For CDN users

First remove the existing <script src> tag from the page:

<script src="https://api.mapbox.com/mapbox-gl-js/v3.25.0/mapbox-gl.js"></script>

Then import the mapboxgl namespace directly from the CDN, making sure to use the script type “module”:

<script type="module">
import * as mapboxgl from 'https://api.mapbox.com/mapbox-gl-js/v3.25.0/esm/mapbox-gl.js';
const map = new mapboxgl.Map({
    accessToken: <ACCESS_TOKEN>,
    container: 'map'...
});
</script>

Lightweight by default. Powerful by design.

The HD Module is the first milestone in a broader roadmap to modularize GL JS. Future releases will continue separating specialized rendering systems into independently loaded modules, allowing Mapbox to introduce increasingly advanced mapping capabilities without increasing the baseline cost for every application.