Mapas e Geolocalização
Regras
- Mapbox GL JS para mapas interativos ricos —
react-map-gl como wrapper para React
- Leaflet como alternativa gratuita —
react-leaflet para React, sem necessidade de chave de API para tiles básicos
- Gerenciamento de chaves de API:
NEXT_PUBLIC_MAPBOX_TOKEN para Mapbox no lado do cliente, nunca exponha segredos do lado do servidor
- Geocodificação: converter endereços em coordenadas — API de Geocodificação do Mapbox ou OpenStreetMap Nominatim (gratuito)
- Agrupamento de marcadores: use
supercluster ou o agrupamento embutido do Mapbox para grandes conjuntos de dados (100+ marcadores)
- Padrão de localizador de lojas: geocodificar localização do usuário → consultar lojas próximas com Haversine/PostGIS → exibir no mapa
- Exibição de rotas: API de Direções do Mapbox para rotas de carro/a pé, renderizar como camada GeoJSON LineString
- Geolocalização do navegador:
navigator.geolocation.getCurrentPosition() — sempre trate a permissão negada com elegância
- Carregar componente de mapa com lazyload — mapas são pesados; use
dynamic(() => import("./Map"), { ssr: false })
Padrões
import Map, { Marker, NavigationControl } from "react-map-gl";
import "mapbox-gl/dist/mapbox-gl.css";
function StoreMap({ stores }: { stores: Store[] }) {
return (
<Map
initialViewState={{ longitude: -122.4, latitude: 37.8, zoom: 11 }}
mapboxAccessToken={process.env.NEXT_PUBLIC_MAPBOX_TOKEN}
mapStyle="mapbox://styles/mapbox/streets-v12"
style={{ width: "100%", height: 400 }}
>
<NavigationControl position="top-right" />
{stores.map((store) => (
<Marker key={store.id} longitude={store.lng} latitude={store.lat}>
<Pin />
</Marker>
))}
</Map>
);
}
function haversineDistance(lat1: number, lon1: number, lat2: number, lon2: number): number {
const R = 6371;
const dLat = ((lat2 - lat1) * Math.PI) / 180;
const dLon = ((lon2 - lon1) * Math.PI) / 180;
const a = Math.sin(dLat / 2) ** 2 + Math.cos((lat1 * Math.PI) / 180) * Math.cos((lat2 * Math.PI) / 180) * Math.sin(dLon / 2) ** 2;
return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
}
Evitar
- Renderizar componentes de mapa no lado do servidor — sempre carregue com
ssr: false ou "use client"
- Renderizar 1000+ marcadores sem agrupamento — prejudica o desempenho; use supercluster
- Codificar coordenadas fixas — geocode endereços em tempo de build ou sob demanda
- Ignorar a negação de permissão de geolocalização — sempre forneça uma alternativa (entrada manual de endereço)