OpenWeather Maps SDK

v0.1.0 · npm · Examples

A modular TypeScript SDK for interactive weather maps on MapLibre GL JS. It replaces a legacy monolithic map widget with a layered architecture: a framework-agnostic core, a WebGL scalar/particle/waves renderer, a MapLibre adapter, and a matching pair of simple UI renderers — one plain-DOM, one React — built on one shared, headless view-model layer.

Consumers get data-encoded Maps 3.0 tiles (client-side colorization), GPU wind particles, ocean wave glyphs, radar/satellite overlays, pressure contours, cyclone tracks, live lightning, point query, city search, and a scrubbable timeline — without bundling any UI unless they want it.

Key features

• Render weather layers with three lines of code. createWeatherMap() resolves an API key, mounts a MapLibre map, and paints the default layer — see Getting Started.
• Bring your own UI, or use ours. Every stateful concern (active layer, timeline, units, overlay toggles, point-query results) lives in framework-agnostic stores. Render them yourself, or drop in the simple <SimpleMapUI> / createSimpleMapUI() demo chrome — plain, unstyled-by-default controls with no art assets and no fan-out/fold layout.
• One view-model, two renderers. @openweather/maps-ui (DOM) and @openweather/maps-react/ui (React) consume the exact same @openweather/maps-ui-core state machines and data-owm-part registry, so they can share one stylesheet and never drift — enforced by a cross-renderer parity test in CI.
• GPU-accelerated rendering. Scalar colorization, particle advection, and wave-glyph rendering run as custom WebGL2 layers (with an automatic WebGL1 fallback) via @openweather/maps-gl.

OpenWeather's own fuller designed UI — a fan-out layer rail, a day-axis timeline, per-overlay config panels, and an expanding search pill — is a second tier alongside the simple kit, on both renderers (./designed, plus createWeatherMapUI/<WeatherMapUI> on ./maplibre), built on the same headless view-models described below. Pair it with @openweather/maps-theme for OpenWeather's own look. The One Call weather detail panel that appears alongside it ships separately as an addon (@openweather/maps-addon-onecall-detail) — One Call 3.0 is a separately subscribed product, so nothing in the SDK itself depends on it.

Core components

Package	Role
@openweather/maps-core	Engine, layer registry, providers, timeline, search, point-query, units/settings stores
@openweather/maps-gl	WebGL custom layers: scalar colorization, particle advection, wave glyphs, contour extraction
@openweather/maps-maplibre	MapLibre adapter — createWeatherMap(), overlay managers, multi-tile assembly, point sampling
@openweather/maps-ui-core	Framework-agnostic view-models for both UI tiers below — no DOM, no React
@openweather/maps-ui	DOM renderer: the simple kit (.) and the designed kit (./designed, ./maplibre)
@openweather/maps-react	React providers, hooks, headless compounds, <WeatherMap>, and both UI kits (./ui, ./designed)
@openweather/maps-theme	OpenWeather's visual styling for the designed UI kit

MapsGL integration

The map shell is plain MapLibre GL JS — no fork, no patched build. Weather visuals are custom WebGL layers inserted below the basemap's coastline strokes so land outlines stay crisp above colorized fields. createWeatherMap() (vanilla) and <WeatherMap>/useWeatherMap (React) both return a WeatherMapHandle / the same handle wrapped in a hook result — the map instance and the weather engine are always one object, never two things you have to keep in sync yourself.

UI building blocks

From most to least abstraction, across two independent kits:

1. <SimpleMapUI> / createSimpleMapUI() — the entire reference demo (status-text shell, layer panel, legend, overlay toggles, timeline range control, search, point-query box, zoom) as one call. See each simple UI kit page for the pieces it's built from.
2. Simple UI kit (@openweather/maps-react/ui, @openweather/maps-ui) — one plain, data-owm-part-stamped control per concern, assembled yourself.
3. <WeatherMapUI> / createWeatherMapUI() — OpenWeather's own designed demo (fan-out layer rail, day-axis timeline, expanding search, per-overlay config panels) as one call, on ./maplibre alongside <SimpleMapUI>/createSimpleMapUI(). Pair with @openweather/maps-theme for the OpenWeather look; add @openweather/maps-addon-onecall-detail for the One Call panel.
4. Designed UI kit (@openweather/maps-react/designed, @openweather/maps-ui/designed) — the same controls the demo above assembles, one per concern, for a custom layout.
5. Headless compounds / view-models (@openweather/maps-react's Timeline/Layers/Search, @openweather/maps-ui-core's stores) — state and behavior with zero markup or styling opinions, shared by both kits, for a fully custom UI.

Concepts

Compound components

React's Timeline, Layers, and Search are compound components (Timeline.Provider, Timeline.Track, Timeline.Scrubber, …) — each sub-component reads from context established by its .Provider and throws a descriptive error if mounted outside one. See Headless Compounds.

Context providers

MapsProviders wires SettingsProvider, MapControllerProvider, and LayersProvider around a CoreMapController (or a WeatherMapHandle's controller) in one call — see Providers & Hooks.

Composition over configuration

Rather than one component with fifty props, each simple-kit control takes a narrow, single-purpose options/props shape (LayerPanelOptions, TimelineSliderProps, …) and the full demo composes them. Nothing stops a consumer from using a few of the simple kit's controls and hand-rolling the rest.

What you can build

• A drop-in weather map matching the reference demo, unmodified.
• The same demo restyled — every part is a plain data-owm-part-stamped element, styleable with ordinary CSS against simple.css.
• A fully custom UI over the headless stores/compounds, using none of the shipped markup.
• A core-only integration with your own renderer (Canvas, WebGL, even a non-map UI) — see Core-only / Custom Renderer.

---

Continue to Getting Started →