Optimization and best practices
This guide explains how to reduce the size of Mapbox GL JS in your application. The most effective optimization is to use the ES module (ESM) entry point, mapbox-gl/esm, which is available when you install Mapbox GL JS from npm.
Use the ESM entry point
Mapbox GL JS ships two entry points in its npm package:
| Entry point | Import | Format |
|---|---|---|
| Default | import mapboxgl from 'mapbox-gl' | A single, self-contained bundle that includes every feature of the library. |
| ESM | import * as mapboxgl from 'mapbox-gl/esm' | A code-split build with a core bundle and optional modules that are downloaded only when your map needs them. |
With the default entry point, your users download the code for every feature, including 3D models, procedural buildings, terrain, weather effects, and style validation, even if your map never uses them. With the ESM entry point, the core bundle contains what every map needs, and the remaining features are fetched at runtime the first time a style, layer, source, or API call requires them.
To switch to the ESM entry point, update your import and pass your access token in the Map options:
import * as mapboxgl from 'mapbox-gl/esm';
import 'mapbox-gl/dist/mapbox-gl.css';
const map = new mapboxgl.Map({
accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
container: 'map',
center: [-74.5, 40],
zoom: 9
});
The ESM entry point requires Mapbox GL JS v3.25.0 or later.
The ESM entry point is distributed through the npm package. If you load Mapbox GL JS from the Mapbox CDN with a <script> tag, you receive the full, single-file bundle. To take advantage of the smaller core bundle, install Mapbox GL JS with npm and use a module bundler.
How the ESM build is organized
The ESM build consists of the files in mapbox-gl/dist/esm/. Your bundler emits the optional modules as separate chunks in your build output, and Mapbox GL JS requests them automatically at runtime, so you don't need to import or configure them yourself.
Core bundle
The core bundle is loaded as soon as your application imports mapbox-gl/esm. It contains everything needed to render and interact with a 2D map:
- The
Mapclass, camera, and user interaction handlers - Markers, popups, and controls
- Vector, raster, raster-dem, GeoJSON, image, and video sources
- The core style layer types:
fill,line,symbol,circle,heatmap,fill-extrusion,raster,hillshade,background,sky, and custom layers - Expressions, symbol placement, and the Web Worker that parses tiles
The core bundle consists of the following files:
| File | Purpose |
|---|---|
mapbox-gl.js | The entry point that you import. |
core.js | The main-thread rendering and API code. |
shared.js | Code shared between the main thread and the Web Worker. |
worker.js | The Web Worker entry point that fetches and parses tiles. |
In Mapbox GL JS v3.32.0, the core bundle is 394 KB with gzip (327 KB with Brotli). The default entry point, which includes every feature, is 518 KB with gzip (411 KB with Brotli), so the JavaScript required to start your map is roughly 20–24% smaller with the ESM entry point.
Optional modules
Optional modules are downloaded on demand. Each one is requested the first time your map uses a feature that depends on it, and is cached by the browser afterwards. If your map never uses a feature, its module is never downloaded.
| Module | Loaded when your map uses | gzip | Brotli |
|---|---|---|---|
Terrain and globe (lite.main.js) | 3D terrain, the globe projection, or layers that are draped over terrain. | 13 KB | 12 KB |
3D content (standard.main.js, standard.shared.js, standard.worker.js) | 3D models for buildings, vegetation, and landmarks (model layers, model and batched-model sources), landmark icons, ground shadows, and ground effects for fill-extrusion layers when 3D lights are enabled. | 32 KB | 28 KB |
Road and building details (hd.main.js, hd.shared.js, hd.worker.js) | Procedural buildings and building facades (building layers), indoor maps, lane details and elevated lines (*-elevation-reference layout properties), particle effects (raster-particle layers), and rain and snow effects. | 53 KB | 46 KB |
Shared 3D model code (hd_standard.model.js, hd_standard.shared.js) | Either of the two modules above. It is downloaded once, by whichever of them loads first. | 13 KB | 11 KB |
Debug (debug.js) | Style validation (enabled by default), style diffing with setStyle(style, {diff: true}), or debug overlays such as map.showTileBoundaries, map.showCollisionBoxes, and map.showPadding. | 12 KB | 11 KB |
Raster array (raster_array.main.js, raster_array.shared.js, raster_array.worker.js) | raster-array sources, such as those used for weather and other multi-band raster data. | 11 KB | 10 KB |
Sizes are measured from the Mapbox GL JS v3.32.0 npm package. They vary between releases and depend on the compression your server uses.
The Mapbox Standard style uses features such as 3D buildings and landmarks, so maps that use Mapbox Standard will load some optional modules at runtime. The core bundle still loads first, so your map can begin initializing before these modules arrive. Maps with simpler styles that don't use these features never download them.
Recommendations
- Use
mapbox-gl/esmin all new projects built with npm. Use the defaultmapbox-glentry point only if your build tools can't consume ES modules. - Don't mix entry points. Importing both
mapbox-glandmapbox-gl/esmin the same application includes the library twice. Import frommapbox-gl/esmconsistently throughout your application code. - Deploy the optional modules with your bundle. Make sure every chunk your bundler emits is deployed and reachable alongside your main bundle, so optional modules can be fetched when they are needed.
- Choose a style that matches your needs. Features such as 3D terrain, globe, 3D models, procedural buildings, and weather effects each load an additional module. If your map doesn't need them, a simpler style avoids those downloads.
- Stay up to date. Each Mapbox GL JS release continues to move code out of the core bundle and into optional modules. Upgrading to the latest version is one of the easiest ways to reduce bundle size.