@planet/maps

@planet/maps

Declarative mapping components

Background

React lets you build interactive UIs with (mostly) declarative syntax. OpenLayers provides an imperative API for building mapping apps. It can be awkward to map React's component API to an imperative API. However, the React team provides a package for creating custom renderers: react-reconciler. This is how they integrate with imperative APIs themselves. The react-dom package uses react-reconciler to provide a mapping to the imperative DOM API. react-native uses react-reconciler to map to imperative native APIs.

This library provides declarative mapping components representing imperative APIs from OpenLayers.

Example

Here is an example of what a map looks like with components from this package:

function MyApp() {
  return (
    <Map style={{width: '100%', height: '100%'}}>
      <View options={{center: [0, 0], zoom: 1}} />
      <WebGLTile>
        <OSM />
      </WebGLTile>
      <ScaleLine />
    </Map>
  );
}

You can also listen to any events on the map, view, controls, interactions, layers, or sources; use refs to get access to the underlying OpenLayers instances; and more.

Design Goals

The purpose of this project is to provide a mapping between React's declarative components and OpenLayers' imperative API. In other words, this project provides a React renderer for OpenLayers.

Here are some of the goals of this project:

• Ideally, the renderer would not have any additional dependencies beyond what is bundled with an OpenLayers map.
• Components exported by this package map 1:1 with classes exported by OpenLayers.
• Component props map directly to properties that are settable on instances of OpenLayers classes. Exceptions to this are props like options (passed to the constructor only), listener props (e.g. onChange), and ref.
• Components accept a ref that provide access to the underlying OpenLayers instance.
• The renderer should add negligible overhead in terms of bundle size, memory consumption, or processing.
• Code components can be generated by using OpenLayers sources. Exceptions to this are the map component (responsible for invoking the custom renderer) and components that map to classes without subclasses (e.g. the view).

Non-Goals

This project does not intend to provide any of the following:

• Higher level abstractions or components that combine logic from multiple OpenLayers instances (e.g. an editable layer component that wraps a layer, source, and editing interactions).
• Styled widgets (e.g. a layer switcher/browser).
• Other utilities for working with vector data, projections, etc.

We hope that this package can provide the foundation for other, higher-level libraries with more opinions about the look and feel of mapping components.

Development

The development setup depends on Node 18 (most things work on 16, but not all).

Install project dependencies:

npm install

The rendering tests use Playwright for visual snapshot comparison. See the tests/rendering/readme.md for more detail.

Prior Art

Other projects like react-openlayers-fiber and react-ol-fiber use a similar approach and provided inspiration for this project. The major difference between this project and those is that this project provides importable components for OpenLayers layers, sources, controls, and interactions. The other projects bundle all of OpenLayers in their renderer. So a simple "hello world" map with one of the existing projects is about 1.5 MB while the same with this project is about 460 KB.