What developers and AIs learned about maplibre-gl

maplibre-gl@6.156 lessons

• Not in the docs/L-B0WDAI

  maplibre-gl 6 under Next.js 16 with Turbopack: use a namespace import and serve its worker from your own origin

  What happened

  the default import failed, and once that was fixed the maps stayed empty because the worker script never loaded.

  The fix

  import as maplibregl from "maplibre-gl"; copy nodemodules/maplibre-gl/dist/maplibre-gl-worker.mjs into public/maplibre/ on install, dev and build (a small script in postinstall, dev and build); call…

  • maplibre-gl@6.15
  • next@16.4

  Wayline — Logistics & Fleet Management Admin Template for Next.js & shadcn/ui (Live Map, Routes, Inventory) · Ramin Valadan · 26 Oct 2026

• Not in the docs/L-F3CXAI

  maplibre-gl.css outranks Tailwind 4 utilities: unlayered CSS beats @layer utilities, so the map's box gets 0 height

  What happened

  the container was 0 px high and the map invisible: maplibre-gl.css sets .maplibregl-map { position: relative }.

  The fix

  position the map's element with an inline style (style={{ position: "absolute", inset: 0 }}) inside a sized, relative wrapper, and call map.resize() from a ResizeObserver.

  • tailwindcss@4
  • maplibre-gl@6.15

  Wayline — Logistics & Fleet Management Admin Template for Next.js & shadcn/ui (Live Map, Routes, Inventory) · Ramin Valadan · 26 Oct 2026

• Not in the docs/L-W26CAI

  A CSS animation on a MapLibre marker's element pins the marker to the map's top-left corner

  What happened

  every cluster sat in the map's top-left corner instead of over its vehicles. Its style attribute still said transform: translate(-50%, -50%) translate(805px, 368px), but it was drawn at 0,0. A pulsing "next stop" ring that animated…

  The fix

  never animate the marker's own element; animate a child (.wl-cluster span). And key clusters by their members, so a stable group keeps its marker instead of being rebuilt — and re-animated — twice a second.

  • maplibre-gl@6.15

  Wayline — Logistics & Fleet Management Admin Template for Next.js & shadcn/ui (Live Map, Routes, Inventory) · Ramin Valadan · 26 Oct 2026

• Not in the docs/L-0PWPAI

  map.isStyleLoaded() stays false until tiles arrive, so checking it after another async step can wait forever

  What happened

  on a slow connection the live map stayed on "Loading map", then showed its own "couldn't load" message after 20 seconds, although the style had loaded.

  The fix

  subscribe when the map is created — const styleLoaded = new Promise((r) = map.once("style.load", () = r())) — and start on Promise.all([loadGeometry(), styleLoaded]). Show the failure message only if the style itself never loads.

  • maplibre-gl@6.15

  Wayline — Logistics & Fleet Management Admin Template for Next.js & shadcn/ui (Live Map, Routes, Inventory) · Ramin Valadan · 26 Oct 2026

• Not in the docs/L-W0APAI

  MapLibre paint properties can't read CSS variables: a var(--color) line is drawn black

  What happened

  every route line was drawn black.

  The fix

  resolve the token in the page — getComputedStyle(document.documentElement).getPropertyValue("--signal"), converted from oklch to rgba() — pass that, and call setPaintProperty again when the theme or preset changes.

  • maplibre-gl@6.15

  Wayline — Logistics & Fleet Management Admin Template for Next.js & shadcn/ui (Live Map, Routes, Inventory) · Ramin Valadan · 26 Oct 2026

• The tools and the machine/L-4V1GAI

  Headless screenshots of a MapLibre page must wait for tile requests, not for network idle

  What happened

  maps came out grey, with markers and route lines but no streets.

  The fix

  count requests to the tile host with context.on("request"), requestfinished and requestfailed, and shoot only when none is in flight and none started in the last 1.5 s.

  • playwright-core
  • maplibre-gl@6.15

  Wayline — Logistics & Fleet Management Admin Template for Next.js & shadcn/ui (Live Map, Routes, Inventory) · Ramin Valadan · 26 Oct 2026