Livewire Mapcn Laravel Package

Product Decisions This Supports

Which roadmap items this collapses into "reuse" instead of "build":

• Logistics, dispatch, and delivery tracking. <x-map-route> with :progress plus progress-model binds the travelled line to an Alpine property, so a playback slider or ETA scrubber animates with zero server round-trips. A "where's my order" replay or an ops dispatch board becomes a frontend-only animation over data you already load — no websocket choreography, no polling loop.
• Coverage, territory, and service-area analysis. <x-map-geojson> ships polygons/lines/points with fill, hover, tooltip, popup slots and fit-bounds. Add <x-map blank> and you can render coverage on no basemap at all — which removes the tile-licensing question entirely for internal analytics views.
• Network, partner, and flow visualisation. <x-map-arc> gives curved connections with hover paint, tooltips, popups and click/hover events, and it composes with projection="globe". "Trade lanes / inter-facility flows / partner network" is a component, not a spike. The globe view is a unusually strong demo and investor-deck asset for a Blade component.
• Store locators, asset registries, field-service maps, site pickers. Once the base map exists, each of these is near-zero marginal cost — markers, popups, tooltips, click-to-drop, draggable-marker-to-Livewire-event.
• Multi-map dashboards. v2 creates maps only when near the viewport, queues commands sent before start, and preloads MapLibre via @livewireMapStyles. A map per row or per site is now a viable design rather than a performance hazard.
• Iterative geographic features. Components inside <x-map> update in place with the camera preserved, and commands take mapId so you can target one map. "Filter by region", "highlight the selected route", "let the user pick among alternatives" stay small edits.

Build vs. buy:

• The rendering layer is commodity — MapLibre is open source, this package is MIT, and v2 adds key-free open providers (openfreemap-liberty with 3D buildings, openfreemap-bright, openfreemap-positron, blank). You are not buying a map vendor contract.
• You are buying the Livewire↔MapLibre reactive bridge: state-driven markers/routes/clusters/arcs/GeoJSON that update without a full re-render, camera preserved, events forwarded back into PHP, WebGL contexts torn down on wire:navigate. That plumbing is where teams burn two to four weeks and where homegrown versions end up brittle.
• Buy for internal tools, admin panels, ops consoles, and MVP/beta customer-facing maps. Build (a thin Alpine + MapLibre island) only when you need something this package doesn't model: drawing/editing tools, heavy custom vector styling, sub-100ms high-frequency interaction, or offline.
• No frontend build coupling: no Node pipeline, no npm lockfile, and in v2 Tailwind is no longer required. Exit cost stays low — the API is Blade components over MapLibre primitives, so a swap to raw MapLibre is a contained rewrite.

Roadmap implication: treat maps as a capability, not a project. v2's arcs, GeoJSON overlays, route progress/playback, route-pinned markers, 3D view and custom controls collapse most of what would have been a "v3" column into the current horizon. Re-sequence territory analytics, network/lane views and delivery-progress playback as cheap additions bundled into existing epics rather than separately funded map work.

When to Consider This Package

Adopt when most of these are true:

• The app is Laravel 11–13 + Livewire 3 or 4 on PHP 8.3+. This is a hard gate in v2 — confirm the runtime before committing a sprint.
• The team lives in Blade and PHP, not React/Vue.
• The map is read-mostly and state-driven: data from Eloquent, filters change, markers/routes/polygons redraw. That is exactly the supported pattern.
• You need the specific primitives it ships: markers with popups/tooltips, clusters, OSRM directions, route progress and route-pinned markers, arcs, GeoJSON, 3D/globe, custom controls. If you need something off that list, evaluate MapLibre directly.
• The surface is internal or authenticated (admin, ops, dispatch, dashboards) where you control traffic and load.
• You are willing to wrap it in your own Blade partials so the exit to raw MapLibre stays a day, not a quarter.

Look elsewhere — or budget hardening — when:

• Public, high-traffic consumer maps. The licensing story improved (free key-free providers, blank mode), but defaults still lean on a CDN-loaded MapLibre, the public OSRM demo router, and CARTO basemaps whose config is flagged non-commercial. Before any launch: self-host assets and tiles, point osrm_url at your own routing service, and get tile licensing reviewed.
• Vendor risk tolerance is low. 25 stars, zero dependents, single maintainer, no downstream production proof. v2 is a genuine maturity signal — documented breaking changes, a real bug-fix list, published upgrade notes — but you are still taking a source dependency. Pin the version and be ready to own the code.
• You need routing at scale or with an SLA — traffic-aware ETAs, fleet optimisation, geocoding. Those are services to buy. Note OSRM directions are session-cached and time out after 10s, a UX assumption you must design around.
• You need offline, custom vector tile pipelines, drawing/editing, or very high-frequency interaction.
• Your frontend isn't Livewire. The entire value proposition is the integration.

Upgrade gate if you're on v1 — treat as P1: v1 shipped defects that were live in your app — every map event reached Livewire listeners twice, doubling server requests; WebGL contexts leaked on wire:navigate; theme changes silently dropped routes and clusters; and cluster popups did not escape feature properties (potentially an injection vector on any map showing user-supplied strings — treat upgrading as security-relevant). Migration is bounded but real: MapLibre v6 is ESM-only (set cdn_url/cdn_css_url to null or point at .mjs, or pin a v5 bundle), re-publish views with --force, remove wire:ignore around maps, and re-check UI against changed defaults (lazy by default, 16px popup/tooltip offset, smaller cluster circles, height="full" = 100%).

Minimum due diligence: read the source for the components you depend on (it's small), confirm release cadence is real, pin the version, and write one integration test asserting your map data shape. Also flag the [lng, lat] coordinate order to the team — it's inverted from the intuitive [lat, lng] and produces silently wrong pins.

How to Pitch It (Stakeholders)

To executives: We can ship interactive, data-driven maps inside our existing Laravel application without adding a frontend stack, a JavaScript build pipeline, or a mapping vendor contract. The library is MIT-licensed and the renderer is open source; the latest release also adds key-free open map styles, so there's no per-map-view fee and no lock-in on tiles or data. It gives us a reusable capability — locations, routes, live delivery progress, coverage polygons, network flows, 3D and globe views — that applies across several roadmap items instead of being rebuilt per feature. The latest release also makes many maps on one page cheap and lets us animate route progress client-side with no extra server load. The caveats are maturity and a platform floor: it's young and single-maintainer, and v2 requires PHP 8.3+ and Laravel 11+. Adopt with a pinned version, prove it on one internal surface, and self-host assets and routing before any customer-facing launch.

To engineering (the honest version):

• It solves the annoying part: keeping MapLibre state in sync with Livewire re-renders while preserving the camera, and cleaning up WebGL contexts on wire:navigate. That's the plumbing we'd otherwise hand-roll and later regret.
• Ergonomics are good: <x-map>, <x-map-marker>, <x-map-route>, <x-map-route-marker>, <x-map-cluster-layer>, <x-map-arc>, <x-map-geojson>, <x-map-control>, plus an event bridge (map:click, map:viewport-changed, map:marker-drag-end, …) and server commands (map:ease-to, map:set-theme, map:update-geojson-{id}, …) that accept a mapId.
• Assets are content-hashed with long-lived cache headers, and Tailwind is no longer required. No npm lockfile to babysit.
• Two things to internalise on day one: coordinates are [lng, lat], and wire:key in loops is mandatory while wire:ignore around <x-map> is forbidden — it breaks the reactivity you're adopting it for.
• Know the exit: it's Blade components over MapLibre primitives. If the abstraction ever chafes, we drop to MapLibre directly without re-architecting.