> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/mapbox-gl-js/ja/llms.txt)

# 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:

```js
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](https://docs.mapbox.com/mapbox-gl-js/ja/guides/get-started/use-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 `Map` class, 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](https://docs.mapbox.com/mapbox-gl-js/ja/example/add-terrain/), the [globe projection](https://docs.mapbox.com/mapbox-gl-js/ja/guides/globe/), 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](https://docs.mapbox.com/style-spec/reference/layers/#building) (`building` layers), [indoor maps](https://docs.mapbox.com/mapbox-gl-js/ja/guides/indoor/), lane details and elevated lines (`*-elevation-reference` layout properties), particle effects (`raster-particle` layers), and [rain](https://docs.mapbox.com/mapbox-gl-js/ja/example/rain/) and [snow](https://docs.mapbox.com/mapbox-gl-js/ja/example/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](https://docs.mapbox.com/map-styles/standard/guides/) 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/esm` in all new projects built with npm.** Use the default `mapbox-gl` entry point only if your build tools can't consume ES modules.
-   **Don't mix entry points.** Importing both `mapbox-gl` and `mapbox-gl/esm` in the same application includes the library twice. Import from `mapbox-gl/esm` consistently 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](https://github.com/mapbox/mapbox-gl-js/releases) is one of the easiest ways to reduce bundle size.