@molecule/app-maps-leaflet

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

@molecule/app-maps-leaflet — a Leaflet-backed provider for @molecule/app-maps. Renders real slippy maps with OpenStreetMap tiles (NO API key). Bond it once at startup and every createMap call shows a real map — the built-in default only paints a grey placeholder panel.

Quick Start

// In your app entry, ONCE — REQUIRED: import 'leaflet/dist/leaflet.css'
// (without that CSS the tiles + markers are mispositioned):
import { setProvider, createMap } from '@molecule/app-maps'
import { provider } from '@molecule/app-maps-leaflet'
setProvider(provider)

// then anywhere (the container element needs an explicit height):
const el = document.getElementById('map') as HTMLElement
const map = await createMap({ container: el, center: { lat: 51.5, lng: -0.12 }, zoom: 12 })
map.addMarker({ id: 'a', position: { lat: 51.5, lng: -0.12 }, popup: 'Here' })
// …later, on unmount: map.destroy()

Type

provider

Installation

npm install @molecule/app-maps-leaflet @molecule/app-maps leaflet
npm install -D @types/leaflet

API

Functions

createProvider()

Creates a Leaflet-backed MapProvider.

function createProvider(): MapProvider

Returns: A MapProvider that renders real OpenStreetMap-tiled maps.

Constants

provider

The default Leaflet map provider, ready to bond with setProvider(provider).

const provider: MapProvider

Core Interface

Implements @molecule/app-maps interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/app-maps'
import { provider } from '@molecule/app-maps-leaflet'

export function setupMapsLeaflet(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-maps ^1.0.1

Runtime Dependencies

• @molecule/app-maps
• leaflet

TWO gotchas that decide whether the map is visible at all:

• Import leaflet/dist/leaflet.css once (app entry). Without it, tiles and markers are mispositioned — the #1 "my Leaflet map looks broken" cause.
• The container needs an explicit height (e.g. style={{ height: 400 }}); a zero-height container renders a blank map.

Markers use a self-contained inline-SVG pin by default (no image-asset wiring — this sidesteps Leaflet's default-icon 404 under bundlers); pass icon for a custom URL. ALWAYS destroy() on unmount — Leaflet attaches DOM + resize listeners, and re-initialising over a live container throws "Map container is already initialized".

getSnapshot() rejects (Leaflet has no built-in export) and getCanvas() returns a best-effort surface — both are WebGL-provider (Mapbox/MapLibre) concepts. Everything else (markers/polylines/polygons/circles/popups/viewport/ fitBounds/project/events) renders for real.

BROWSER-ONLY: draws to the DOM via Leaflet. Import + wire from app/client code.