Content
'\n});\n\nmarker.addListener('click', () => {\n infowindow.open(map, marker);\n});\n```\n\n### Mapbox GL JS\n\n```javascript\n// Option 1: Attach to marker\nconst marker = new mapboxgl.Marker()\n .setLngLat([-122.4194, 37.7749])\n .setPopup(new mapboxgl.Popup().setHTML('Content
'))\n .addTo(map);\n\n// Option 2: On layer click (for data-driven markers)\nmap.on('click', 'points-layer', (e) => {\n const coordinates = e.features[0].geometry.coordinates.slice();\n const description = e.features[0].properties.description;\n\n new mapboxgl.Popup().setLngLat(coordinates).setHTML(description).addTo(map);\n});\n```\n\n## Migration Strategy\n\n### Step 1: Audit Current Implementation\n\nIdentify all Google Maps features you use:\n\n- [ ] Basic map with markers\n- [ ] Info windows/popups\n- [ ] Polygons/polylines\n- [ ] Geocoding\n- [ ] Directions\n- [ ] Clustering\n- [ ] Custom styling\n- [ ] Drawing tools\n- [ ] Street View (no Mapbox equivalent)\n- [ ] Other advanced features\n\n### Step 2: Set Up Mapbox\n\n```html\n\n\n\n```\n\n### Step 3: Convert Core Map\n\nStart with basic map initialization:\n\n1. Replace `new google.maps.Map()` with `new mapboxgl.Map()`\n2. Fix coordinate order (lat,lng -> lng,lat)\n3. Update zoom/center\n\n### Step 4: Convert Features One by One\n\nPrioritize by complexity:\n\n1. **Easy:** Map controls, basic markers\n2. **Medium:** Popups, polygons, lines\n3. **Complex:** Clustering, custom styling, data updates\n\n### Step 5: Update Event Handlers\n\nChange event syntax:\n\n- `google.maps.event.addListener()` -> `map.on()`\n- Update event property names (`latLng` -> `lngLat`)\n\n### Step 6: Optimize for Mapbox\n\nTake advantage of Mapbox features:\n\n- Convert multiple markers to data-driven layers\n- Use clustering (built-in)\n- Leverage vector tiles for custom styling\n- Use expressions for dynamic styling\n\n### Step 7: Test Thoroughly\n\n- Cross-browser testing\n- Mobile responsiveness\n- Performance with real data volumes\n- Touch/gesture interactions\n\n## Gotchas and Common Issues\n\n### Coordinate Order\n\n```javascript\n// Google Maps\n{ lat: 37.7749, lng: -122.4194 }\n\n// Mapbox (REVERSED!)\n[-122.4194, 37.7749]\n```\n\n**Always double-check coordinate order!**\n\n### Event Properties\n\n```javascript\n// Google Maps\nmap.on('click', (e) => {\n console.log(e.latLng.lat(), e.latLng.lng());\n});\n\n// Mapbox\nmap.on('click', (e) => {\n console.log(e.lngLat.lat, e.lngLat.lng);\n});\n```\n\n### Timing Issues\n\n```javascript\n// Google Maps - immediate\nconst marker = new google.maps.Marker({ map: map });\n\n// Mapbox - wait for load\nmap.on('load', () => {\n map.addSource(...);\n map.addLayer(...);\n});\n```\n\n### Removing Features\n\n```javascript\n// Google Maps\nmarker.setMap(null);\n\n// Mapbox - must remove both\nmap.removeLayer('layer-id');\nmap.removeSource('source-id');\n```\n\n### Updating Data Without Flash\n\n**Never** remove and re-add layers to update data — this reinitializes WebGL resources and causes a visible flash. Instead:\n\n```javascript\n// ✅ Update data in place (no flash)\nmap.getSource('stores').setData(newGeoJSON);\n\n// ✅ Filter existing data (GPU-side, fastest)\nmap.setFilter('stores-layer', ['==', ['get', 'category'], 'coffee']);\n\n// ❌ BAD: remove + re-add causes flash\nmap.removeLayer('stores-layer');\nmap.removeSource('stores');\nmap.addSource('stores', { ... });\nmap.addLayer({ ... });\n```\n\n## When NOT to Migrate\n\nConsider staying with Google Maps if:\n\n- **Street View is critical** - Mapbox doesn't have equivalent\n- **Tight Google Workspace integration** - Places API deeply integrated\n- **Already heavily optimized** - Migration cost > benefits\n- **Team expertise** - Retraining costs too high\n- **Short-term project** - Not worth migration effort\n\n## Quick Reference: Side-by-Side Comparison\n\n```javascript\n// GOOGLE MAPS\nconst map = new google.maps.Map(el, {\n center: { lat: 37.7749, lng: -122.4194 },\n zoom: 12\n});\n\nconst marker = new google.maps.Marker({\n position: { lat: 37.7749, lng: -122.4194 },\n map: map\n});\n\ngoogle.maps.event.addListener(map, 'click', (e) => {\n console.log(e.latLng.lat(), e.latLng.lng());\n});\n\n// MAPBOX GL JS\nmapboxgl.accessToken = 'YOUR_TOKEN';\nconst map = new mapboxgl.Map({\n container: el,\n center: [-122.4194, 37.7749], // REVERSED!\n zoom: 12,\n style: 'mapbox://styles/mapbox/streets-v12'\n});\n\nconst marker = new mapboxgl.Marker()\n .setLngLat([-122.4194, 37.7749]) // REVERSED!\n .addTo(map);\n\nmap.on('click', (e) => {\n console.log(e.lngLat.lat, e.lngLat.lng);\n});\n```\n\n**Remember:** lng, lat order in Mapbox!\n\n## Additional Resources\n\n- [Mapbox GL JS Documentation](https://docs.mapbox.com/mapbox-gl-js/)\n- [Official Google Maps to Mapbox Migration Guide](https://docs.mapbox.com/help/tutorials/google-to-mapbox/)\n- [Mapbox Examples](https://docs.mapbox.com/mapbox-gl-js/examples/)\n- [Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/)\n\n## Integration with Other Skills\n\n**Works with:**\n\n- **mapbox-web-integration-patterns**: Framework-specific migration guidance\n- **mapbox-web-performance-patterns**: Optimize after migration\n- **mapbox-token-security**: Secure your Mapbox tokens properly\n- **mapbox-geospatial-operations**: Use Mapbox's geospatial tools effectively\n- **mapbox-search-patterns**: Migrate geocoding/search functionality\n\n## Reference Files\n\nThe following reference files contain detailed migration guides for specific topics. Load them when working on those areas:\n\n- **`references/shapes-geocoding.md`** — Polygons, Polylines, Custom Icons, Geocoding\n- **`references/directions-controls.md`** — Directions/Routing, Controls\n- **`references/clustering-styling.md`** — Clustering, Styling/Appearance\n- **`references/data-performance.md`** — Data Updates, Performance, Common Migration Patterns (Store Locator, Drawing Tools, Heatmaps)\n- **`references/api-services.md`** — API Services Comparison, Pricing, Plugins, Framework Integration, Testing, Migration Checklist\n\nTo load a reference, read the file relative to this skill directory, e.g.:\n\n```\nLoad references/shapes-geocoding.md\n```\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}