mapbox-gl-js
mapbox-gl-js copied to clipboard
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 [email protected]
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
andFillPaint
. Instead, use TypeScript Indexed Access TypeFillLayerSpecification['layout']
for layout properties andFillLayerSpecification['paint']
for paint properties. - Source implementation types in GL JS are exported without the
Impl
suffix. For example,VectorSourceImpl
is exported asVectorSource
. - Community typings'
Any*
types follow the same pattern:AnySourceData
becomesSourceSpecification
in GL JS,AnyLayer
becomesLayerSpecification
, andAnySourceImpl
becomesSource
.
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.