mapbox-google-maps-migration_skill

Overview

This skill provides a concise, practical migration guide for developers moving from Google Maps Platform to Mapbox GL JS. It focuses on API equivalents, shifting patterns from imperative objects to declarative data sources and layers, and highlights performance and styling differences. Use it to speed up migration planning and reduce common pitfalls.

How this skill works

The guide inspects common Google Maps constructs (map initialization, markers, info windows, shapes, controls, geocoding, directions, clustering, and styling) and maps them to Mapbox GL JS equivalents. It explains coordinate differences, authentication changes, event name mappings, and when to prefer Mapbox’s data-driven layers over DOM-based markers for performance. Sample code patterns show both one-to-one replacements and recommended, scalable approaches.

When to use it

• When replacing Google Maps API calls with Mapbox GL JS equivalents
• When converting marker-heavy apps to performant WebGL layers
• When migrating map styles, controls, and event handlers
• When switching geocoding and directions calls to Mapbox APIs
• When creating custom icons, clustering, or route rendering

Best practices

• Treat geographic objects as data: add GeoJSON sources and style with layers instead of manipulating many object instances
• Remember coordinate order: Mapbox uses [lng, lat] everywhere
• Use symbol or circle layers for 100+ points; use DOM markers only for small sets or custom HTML needs
• Load and add images via map.loadImage and map.addImage for fast symbol rendering
• Prefer Mapbox API endpoints (Geocoding, Directions) or official plugins for advanced features

Example use cases

• Convert a Google Maps marker list to a clustered Mapbox GeoJSON source + layers for thousands of points
• Replace Google Maps InfoWindows with Mapbox Popups attached to markers or layer clicks
• Migrate route rendering from DirectionsRenderer to Mapbox Directions API and draw LineString layers
• Recreate custom-styled basemaps using Mapbox Studio and setStyle with a style URL
• Swap map controls and add explicit NavigationControl, FullscreenControl, GeolocateControl, and ScaleControl