Configure Terrae's map runtime

Choose the Map item's target from the application, not from the demo site's defaults.

Mapbox GL

The Mapbox target installs mapbox-gl, imports mapbox-gl/dist/mapbox-gl.css, and defaults to Mapbox light and dark style URLs. Create a public token with only the scopes the chosen styles require and pass it through the accessToken prop. A Next.js app may read NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN, but the component itself accepts a string and does not require that variable name. Review Mapbox pricing and terms for the expected map loads, tiles, and styles.

MapLibre GL

The MapLibre target installs maplibre-gl, swaps the adapter import and stylesheet, and needs no Mapbox token. Terrae's default MapLibre styles are CARTO Positron and Dark Matter URLs. Those basemaps are a separate network service with separate terms. Replace them through the Map style prop or the light/dark styles pair when the application uses another MapLibre-compatible provider or self-hosted tiles.

The Rain component and Mapbox Standard styles are Mapbox-only. Other components use the shared adapter, but test them against the chosen engine because an upstream map API can have engine-specific behavior.

Application boundary

Render maps from a client component. Give the map element and every flex/grid ancestor a real height; h-full works only when its ancestors establish one. Keep the engine CSS import exactly once. Terrae uses next-themes to select the light or dark style unless a fixed style is supplied, so mount the application's theme provider above the map or pass explicit styles.

Every current feature-item JSON declares mapbox-gl directly and also names the Mapbox base item, even though Terrae documents the MapLibre base as compatible. If the application uses MapLibre, apply the MapLibre base target after each feature delivery so its adapter wins, then inspect imports and dependencies. Expect mapbox-gl to remain installed until the application deliberately reconciles that upstream declaration; do not silently remove it while delivered files still import its types.

Allow the selected style, tile, glyph, sprite, image, and media origins in Content Security Policy and CORS. Do not expose secret provider tokens in client code. Test token failures, blocked tiles, dark-mode changes, resize, unmount/remount, and the production CSP before calling the integration complete.

Integrate animated overlays safely

Install the base Map target and render each overlay inside its Map context. Use stable and unique ids for sources, layers, images, and effects. Avoid creating ids during render because a rerender can orphan the prior map resource.

Keep animation inputs stable with memoized coordinate arrays and data objects. When a route, tab, or dialog hides the map, pause application-driven animation where the component exposes a control hook. On unmount, preserve the source component's cleanup so animation frames, event listeners, markers, sources, layers, images, and media do not accumulate.

Treat reduced motion as a product requirement. Disable auto-start or continuous loops when the application honors prefers-reduced-motion, and provide a still state that preserves the information. Camera-follow and moving-route experiences need a visible pause or stop control when motion lasts more than a brief transition.

Large particle counts, many simultaneous effects, animated GeoJSON updates, video textures, and multiple map instances can be expensive. Measure on representative mobile hardware and with the real data volume. Comparison and synchronized-map components create separate map instances; count every instance in tile requests and provider billing.

Remote GeoJSON, images, and video must be reachable by the browser with suitable CORS. Keep autoplay video muted, provide compatible formats, validate remote data, and do not use a demo asset whose license is unknown in a production composition.