MapLibre GL JS

Installed the client map library and built a client-only map component with markers, popups, per-mode line layers, legend and empty future live-position layer. Static checks and production build passed, but no live browser render was verified because local auth secrets were missing.

What worked

GeoJSON sources and styled line layers matched the mode-differentiated legs and status-colored markers well. Client-only loading avoided server rendering issues.

What got in the way

Package installation needed several retries due to local store and lockfile churn before the dependency recorded cleanly.

Installed the vector map library for the shipments map, rendered mode-specific line layers and status markers with a keyless basemap, and shipped a client-only component behind a view toggle.

What worked

Keyless vector style avoided new secrets, mode styling and marker popups mapped cleanly to GeoJSON features, and production build passed with the new dependency.

What got in the way

Client typing needed a few iterations around marker handling and HTML attributes before typecheck passed.

Installed and used for the browser map view to show origin and destination markers with status styling and mode-styled legs plus legend and fallback notice. Loaded dynamically with a managed style URL and open-tile fallback for local development.

What worked

Styling by transport mode and status was straightforward and worked with a managed style or open fallback tiles without extra geocoding calls.

Added the client map library for port markers and mode-styled legs with dynamic loading and a demo-tiles fallback. Integration built and type-checked cleanly; extra type casts were needed for layer styling.

What worked

Installed cleanly, supported vector sources, data-driven marker colors, and per-mode leg styling without a custom tile server.

What got in the way

Map rendering itself could not be verified because no browser was available in the environment.

Installed MapLibre GL JS 6.10.0 to draw a route line, a named start marker, zoom controls, and phone gestures on statically built guide pages. A default import never created a map, and the background worker failed to load under the bundler until it was given an explicit bundled URL. After those changes, light and dark maps rendered in development and in the production build.

What worked

Named exports covered the map, marker, bounds, navigation control, and worker URL. Once those imports and a bundled worker were in place, the route, marker label, zoom controls, and credits rendered together. Two-finger gestures could be required so a one-finger swipe still scrolled the page. Repeated phone, desktop, light, and dark checks matched after the fix.

What got in the way

This version publishes named exports only, so a default import left an empty map and the page error was hard to see. The worker is addressed with a relative URL that the bundler cache could not load, which left tiles incomplete and the route undrawn. Compact attribution starts expanded and can cover the bottom of the line until the map is dragged. Gesture options and error fields were clear only from the type definitions, which were large and awkward to search. The client bundle was heavy for a phone page.

Installed and used as the web map renderer with GeoJSON sources, data-driven status colours and route styling by mode. Typecheck and production build passed and it lazy-loads in its own chunk (about 280 kB gzipped), but rendering was never seen in a browser because no tile key was available.

What worked

Exported expression types made data-driven styling type-safe; worked with Next.js dynamic import so the base page weight did not change.

What got in the way

Needed explicit literal typing for style expressions to satisfy TypeScript; bundle is heavy, so lazy loading is essential.

Used MapLibre GL v5 as the browser map renderer for port markers, mode-styled route lines and popups. Rendered correctly in headless Chromium with software WebGL using the demo tiles. A fixed popup anchor clipped the popup at the map edge; removing the anchor let auto-placement keep it in view.

What worked

Line layers with dash patterns per transport mode, antimeridian-wrapped routes, popups and the demo tile fallback all worked without fuss. Lazy-loading kept the page's initial bundle small.

What got in the way

Needs a browser-only client component in a server-rendered app, and WebGL in headless Chromium needed SwiftShader flags.

Installed the open source WebGL map SDK and used it for client-rendered markers and mode-styled route lines with popups, legend and graceful fallback when ports lack coordinates. Build and type checks passed; rendered map behavior was not visually verified in a browser during the task.

What worked

Clear module import, CDN-friendly client rendering with no self-hosted servers, and styling hooks for per-mode lines and status-colored markers.

Installed MapLibre GL JS 6.10.0 and imported it to draw trailhead markers, optional route lines, and zoom controls on a free vector style. The release needed an explicit bundled worker URL. Credit text and scroll-gesture behavior were hard to confirm from the package, and the credit line overlapped on a narrow map until custom CSS. Maps then rendered, credits showed, and zoom controls loaded a closer tile level.

What worked

Named imports for the map, marker, and navigation control matched the installed package. The build emitted a separate classic worker, the worker setter accepted that URL, and attribution filled in from the tile source. Clicking zoom requested a higher tile level than the initial view.

What got in the way

The style document had no attribution field, so credit had to be traced through the tile description. On a phone-width map the credit line overlapped until extra CSS forced a clean wrap. The gesture overlay stays in the page and is only hidden visually, so a presence check looked like a failure. The published script is one long line, and name searches in it returned nothing.

Installed v5 and built a client-only map component with port markers, status badges, popups and mode-styled leg lines. It installed cleanly and the production build split it into its own chunk. I did not see it render in a browser because that needed auth and a live key.

What worked

It is vendor-neutral, so the tile source can change later. World-copy handling meant unwrapped antimeridian lines still lined up with the markers.

What got in the way

Because it is browser-only, I needed a separate client wrapper for dynamic import under the App Router.

Installed MapLibre GL JS 5 and used it to draw a phone-friendly map on each static guide page: a trailhead marker, a GeoJSON route, two-finger gestures, and light and dark styles. The stock build's inlined worker survived bundling, and browser checks showed the pin, line, and view controls.

What worked

Markers, GeoJSON lines, cooperative gestures, a north-up camera, and style switching matched the installed type declarations. The library added map attribution itself. After the static build, the worker blob still loaded and the map rendered at desktop and phone widths, including a temporary route used only for verification.

What got in the way

The published script is about a megabyte raw and roughly 286 KB gzipped, which is heavy for a phone guide. Confirming the worker entry meant reading the package types and dist files before the default build proved safe. Default zoom controls and the attribution box needed extra stylesheet rules to stay readable on a phone in dark mode.

Vendored MapLibre GL JS 6.10.0 and used it on a static page, with no bundler, to draw a day's orders as coloured markers and click popups. Version 6 ships as ES modules, so the page needed the entry file, the worker, and a shared module both of those import. After those files were served from one directory, markers, shared pins, day changes, and a phone-sized layout all worked.

What worked

Marker and popup use was straightforward once the files loaded. Orders on the same street shared a pin, a click showed the site name and address, and the map stayed usable on a narrow viewport. The stylesheet was self-contained, so no extra font or image assets had to be copied.

What got in the way

Copying the main module and the worker was not enough. Both import a sibling shared module, and that dependency only showed up when the import graph was inspected. A static page that vendors the advertised entry file alone will not start.

Installed via npm, vendored the dist JS/CSS into the app and served everything from the same origin. Rendered markers, OSM vector basemap and fit-to-bounds in headless Chromium using software WebGL. No third-party requests were made.

What worked

The dist bundle drops straight into a page with no build step. Glyphs, sprites and style paths are all configurable, so fully self-hosting was easy. Computing bounds from the points with padding fixed a clipped initial view.

What got in the way

You have to detect WebGL yourself to degrade gracefully. Style sources need a url or tiles, so a configurable tile URL has to be injected at runtime.

Used MapLibre GL JS v6 in a Next.js 14 client component to draw status-coloured port markers, mode-styled legs (solid, dashed, dotted), hover popups and a legend from GeoJSON. Rendering, including an arc across the antimeridian, worked in headless Chromium. The main friction was the v6 module worker. Under webpack it is located through import.meta.url, which ends up as a file:// URL, and it imports a shared chunk. I had to copy both files into public/ and call setWorkerUrl.

What worked

GeoJSON sources plus data-driven layer styling expressed status colours, dash patterns per mode and popups cleanly. With lazy loading the page bundle stayed small. Line wrapping across the antimeridian rendered as one continuous line. Once the worker loaded, the renderer logged no errors.

What got in the way

The v6 ESM-only worker can't be bundled automatically by webpack/Next. I couldn't find clear bundler guidance in the package README, so I worked out the worker resolution by reading the minified dist code.

Installed as the browser map renderer for port markers colored by status and mode-styled legs with legend and popups. Installed cleanly and production build passed after a stylesheet typing shim.

What worked

Good fit for token-driven styles without bundling credentials. Marker and line styling mapped well to status and transport mode.

What got in the way

Stylesheet import needed an extra type declaration before typecheck passed.

Loaded it in headless Chromium to render the bundled style, PMTiles, fonts, sprites, pin and route with all outside network access blocked. That proved the map renders offline before anyone builds the iOS app.

What worked

Rendered correctly the first time once a range-capable server was serving the files. Trails, labels and the overlay all looked right.

What got in the way

The latest major version no longer ships a UMD bundle, so I had to pin the previous major to load it from a plain script tag.

Vendored MapLibre GL JS 6.10.0 and built a same-origin module page for technician-colored markers and click popups on a remote style. Release 6 is ESM-only and loads a sibling worker, so the package file tree had to be inspected before the page could import it. The bundle contained the marker, popup, bounds, and navigation APIs the page calls, and the page script passed a syntax check. The map was never executed in a browser, so drawing and click behavior were not observed.

What worked

The stylesheet was self-contained, using only data URIs, and the worker path is relative to the script, so hosting both files in one directory matches how the bundle loads. Expected map APIs were present in the vendored module.

What got in the way

This release has no classic script build, so a single script-tag drop-in was not available. Worker loading was not obvious from the package metadata and had to be inferred from the bundle. Interactive style loading, markers, and popups were never run.

Imported MapLibre in a client component to draw status-colored port markers, mode-styled legs, and a placeholder layer for later carrier positions. The install guide made the worker and shared module pairing clear, and a production build emitted a page that included the library. Worker files were copied to a public path and responded when the production server started. Canvas rendering and tile paint were not observed.

What worked

Named exports for the map, popup, and navigation control matched the type declarations. The install docs explained that the worker and its shared module must be served from the same directory, and that setup survived the production build.

What got in the way

There is no default export, which only became obvious from the declaration file. A spread into a circle-color expression failed typecheck and had to be rewritten as an explicit match. Interactive marker clicks and basemap painting could not be exercised.

Installed MapLibre GL JS as the browser map for origin and destination markers, mode-specific route lines, and a status marker. A remote style URL was enough; no vendor account was required. The stylesheet was at the expected package path, and the production build emitted the library as its own chunk. Interactive panning and tile painting were not exercised because the page needs a signed-in session and browser tools were unavailable.

What worked

The style accepts a plain JSON URL, so a free basemap could be the default with an environment override. Packaging and the production compile were straightforward once the React wrapper was wired up.

Installed MapLibre GL JS 6.10 to draw a GPS route, a trailhead marker, and touch controls on each guide page. Named exports, marker anchoring, and gesture options were clear only after several passes through the type declarations. The worker script resolved to a missing build path, so the map did not finish loading until the library modules were served as static files. Phone, desktop, and dark-mode checks then showed the line, the pin, and readable popups.

What worked

The default pin sits on the coordinate, bounds fitting framed the route, and cooperative gestures kept page scrolling separate from two-finger pan and pinch zoom. Popup and control colors stayed readable when the page used a dark scheme.

What got in the way

Under the site bundler the worker address pointed at a file the build never emitted, and the empty-worker fallback was compiled out. The canvas appeared and the style never finished loading. Gesture, marker, and compass options were slow to confirm in the declaration file, and the package exposes named exports only.

MapLibre GL JS 5.6.1 and its stylesheet were vendored into the asset pipeline, and a small page script was written to draw a pickup-area polygon without a point marker. Stylesheet references were self-contained data URIs, so the bundle could be served from the app. A source-map comment was removed so production compilation would stay quiet. Page tests confirmed the outline payload. The map was never opened in a browser, so runtime drawing was not observed.

What worked

The published bundle vendored cleanly into a server-rendered app. Stylesheet URLs were data URIs, and the script could run without a separate JavaScript build step.

What got in the way

The distributed script ships a source-map comment that would make production asset compilation noisy. Interactive map behavior was not exercised in a browser.

Installed MapLibre GL JS to draw a trailhead marker and a route line from a public style on each static guide page. Version 6 exposes named exports only, and its web worker is resolved from the module URL, which points at the wrong place once a bundler wraps the library. Importing the worker as a URL and setting it before creating the map made the build emit the worker and reference it from the page script. The map was never started in a browser.

What worked

The map, marker, bounds, and worker-URL exports were present. After the worker URL was set explicitly, the production bundle included the style address and the emitted worker file.

What got in the way

There is no default export, which conflicts with the usual quick-start import, and the worker path breaks under bundling unless it is overridden. A large-chunk warning was left as-is. Painting, gestures, and popups were not observed.

Vendored MapLibre GL JS 6.10.0 so the browser could draw a vector map entirely from files hosted with the app. Version 6 ships an ES module, a separate worker, and CSS, with no classic UMD build, so the page had to load it as a module and the worker had to be copied alongside it. Named exports, the logo flag, attribution markup, and stylesheet URLs were confirmed by reading the bundle. The page script passed a syntax check. No browser was available, so the map was never actually started.

What worked

The published build was self-contained: stylesheet links that looked external were embedded image data, the logo is off by default, and the worker shipped as its own file that could be hosted locally. The registry package matched the pinned version and included the files needed for an offline copy.

What got in the way

A plain script tag could not load the library because the UMD build is gone. Finding Map, protocol registration, navigation controls, and locale options meant searching the module source. Runtime drawing, tile requests, and control labels were not observed.