Migrating from `@types/mapbox-gl` to first-class TypeScript typings

Migrating from @types/mapbox-gl to first-class TypeScript typings

The GL JS v3.5.0 release marks a significant transition for GL JS, moving from Flow to TypeScript. While we have maintained backward compatibility where possible, the community typings @types/mapbox-gl are not fully compatible with the new first-class typings. Users relying on the community typings may experience breaking changes. This guide will help you migrate to the new first-class typings and resolve common issues.

Please feel free to comment on this issue if you encounter difficulties during migration. Share your experiences and suggestions to support one another.

Updating GL JS

Install the latest version of GL JS and remove the @types/mapbox-gl dependency.

npm install mapbox-gl@3.5.0
npm uninstall @types/mapbox-gl

Run the TypeScript compiler (tsc) to check for the errors.

Common issues

The migration should be straightforward since there's no need to change how you interact with the API; only the types have changed. However, you may encounter some common issues.

Dangling @types/mapbox-gl

Ensure you're using the latest version of GL JS and have removed the @types/mapbox-gl dependency.

Deprecated Features

Community typings provided features deprecated since v1 and v2, such as the optimizeForTerrain map option, tiledata and tiledataloading events, zoom and property functions, certain exports like the mapboxgl.Control. Please refer to the compatibility test suite in test/build/typings/compatibility-test.ts, used to test first-class typings compatibility with the community typings. Tests incompatible with mapbox-gl typings are marked with @ts-expect-error - incompatible.

Naming Conventions

Community typings' naming convention slightly differs from those provided with GL JS:

• Style-Spec JSON objects in GL JS are suffixed with *Specification (e.g., StyleSpecification, LayerSpecification), whereas in @types/mapbox-gl, there's no suffix (e.g., Style, AnyLayer).
• GL JS doesn't provide separate layout and paint property types like FillLayout and FillPaint. Instead, use TypeScript Indexed Access Type FillLayerSpecification['layout'] for layout properties and FillLayerSpecification['paint'] for paint properties.
• Source implementation types in GL JS are exported without the Impl suffix. For example, VectorSourceImpl is exported as VectorSource.
• Community typings' Any* types follow the same pattern: AnySourceData becomes SourceSpecification in GL JS, AnyLayer becomes LayerSpecification, and AnySourceImpl becomes Source.

Note: We've created aliases where possible (e.g., MapboxOptions as an alias to MapOptions) and marked these aliases as @deprecated in the first-class typings (this might be visible in your editor, e.g., with strikethrough style in VSCode IntelliSense). However, due to potential collisions, we couldn't create aliases for all cases. For example, we couldn't alias Source to SourceSpecification because GL JS already exports Source (same as AnySourceImpl in community typings). We recommend using the new naming convention, but aliases will help you migrate smoothly. Please note that these deprecated types will be removed in future releases.

Start by reviewing the migration sections in the issue and the compatibility test at test/build/typings/compatibility-test.ts. Check where the project documents GL JS TypeScript usage, then ensure the guide covers dependency removal, compiler checks, deprecated features, naming differences, and available aliases. Done means the migration guidance is published in the appropriate documentation location and matches the compatibility tests.