@planet/maps

Declarative mapping components

Use

npm install @planet/maps

See the planetlabs.github.io/maps website for more details and examples using the library.

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.

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

Start the development server:

npm start

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

Before running tests for the first time, install the required Playwright browser:

npx playwright install chromium

Run the tests:

npm test

After updating the ol package to a new version, the generated component sources should be updated:

npm run generate

To publish a new release, choose the release type, update the package.json version and create a tag with npm version, and then push the change:

npm version minor
git push --tags origin main

After pushing the changes, draft release notes based on the tag and publish the GitHub release.

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.