- How do I install kwasii/livewire-mapcn in a Laravel app?
- Run composer require kwasii/livewire-mapcn. Then add the @livewireMapStyles and @livewireMapScripts Blade directives and drop the x-map component into a view. Config and assets can optionally be published, but defaults are served automatically. No Node or npm pipeline is required.
- Which Laravel, Livewire, and PHP versions does livewire-mapcn support?
- The package targets PHP 8.3+, Laravel 11 through 13, and Livewire 3 or 4. Confirm these constraints in composer.json before committing to a sprint because the version gate is hard. It is designed for Livewire apps, so React, Vue, or Inertia frontends lose the main benefit.
- How do Livewire properties keep the map reactive without custom JavaScript?
- You bind center, zoom, markers, and other state to public Livewire properties, and the package reconciles MapLibre layers in place on each re-render. It preserves the camera, forwards MapLibre events into PHP listeners, and tears down WebGL contexts on wire:navigate. That means common updates like moving the viewport or changing markers do not need manual JS wiring.
- Why are my map markers in the wrong location with livewire-mapcn?
- The coordinate contract is [lng, lat], which is inverted from the intuitive lat/lng order. Passing latitude first produces silently wrong pins rather than an error, so the defect survives QA. Double-check every marker, center, and route coordinate array.
- Does livewire-mapcn support markers, clusters, popups, routes, and GeoJSON?
- Yes. The component surface includes x-map, x-map-marker, x-map-popup, x-map-cluster-layer, and x-map-route, plus GeoJSON and arc support. These are declared in Blade from Eloquent-backed Livewire properties. A simple map takes an afternoon; clustering, routes, and popups take a few days.
- What changed in livewire-mapcn v2 and should I upgrade?
- v2 is a breaking release with a documented upgrade guide and honest changelog. It fixes cluster popups that failed to escape feature properties, which was a potential injection vector for user-supplied strings, and a bug that delivered every map event to Livewire listeners twice, doubling server requests. If you run v1 in production, treat the upgrade as high priority.
- I published the config and my map assets fail to load after upgrading — why?
- MapLibre v6 is ESM-only, so the CDN and asset-loading path, including cdn_url, cdn_css_url, and published config, is a concrete failure mode for anyone who published config on v1. Republish or update the config so the package can serve compatible assets. Leaving config unpublished and using defaults avoids this path.
- When should I not use livewire-mapcn and choose raw MapLibre instead?
- Skip it for JS islands, drawing or editing tools, offline tiles, sub-100ms high-frequency interaction, or custom vector styling. Those need raw MapLibre GL JS or a dedicated JS layer. It is also the wrong fit if your frontend is React, Vue, or Inertia rather than Livewire.
- What licensing and production concerns should I review before launching livewire-mapcn?
- The defaults rely on a public OSRM demo router with a 10-second timeout and no SLA, and on CARTO basemaps whose config is flagged non-commercial. Review tile licensing before any public launch and self-host assets or point osrm_url at your own router. For routing at scale, geocoding, traffic-aware ETAs, or fleet optimisation, buy a service such as Mapbox, Google, HERE, or self-hosted OSRM or Valhalla.
- Is kwasii/livewire-mapcn safe to depend on in production?
- It is young, with roughly 25 stars, no dependents, and a single maintainer, so the dominant risk is vendor rather than technical. There is no public proof of production use, so pin the version, read the small source for components you depend on, and decide who owns the fork if maintenance stops. The reconciliation layer is the real value; the MapLibre renderer underneath is free and permissively licensed.