rlayers

Rendering map components on the server is complex because OpenLayers relies on browser-specific APIs (like Canvas and layout engines) that are unavailable in a Node.js environment.

Currently, there is no comprehensive SSR solution for rlayers. Recommended strategies for handling initial map loads include:

1. WMS-compatible server (e.g., GeoServer): Serve prerendered maps over WMS to provide an initial image that is later replaced by a client-side canvas.
2. Static Placeholders: Prerender one or more static images (one per screen size) to serve as temporary placeholders until the client-side map loads.
3. Tile Pushing: Push initial tiles to avoid a high volume of HTTP requests during the first load.

Note: Experimental SSR support for raster layers on fixed map sizes exists in the ssr branch of this repository, but as of March 2022, this support is considered stale and is not actively maintained.

To achieve high performance, especially when using high-frequency events like pointermove, avoid passing anonymous objects, arrays, or functions (lambdas) as component properties. These cause unnecessary re-renders because their references change on every render cycle.

Use React.useMemo and React.useCallback to stabilize references:

Bad (re-evaluates every frame):

<RFeature
    geometry={new Point(fromLonLat([2.295, 48.858]))}
    onClick={(e: MapBrowserEvent) => process(e.target)}
/>

Good (memoized):

<RFeature
    geometry={React.useMemo(() => new Point(fromLonLat([2.295, 48.858])), [])}
    onClick={React.useCallback((e: MapBrowserEvent) => process(e.target), [])}
/>

Performance Tips:

• Memoize whole components or groups of components for significant boosts.
• If performance is poor during pointermove, identify which components are updating at every frame.
• Group features that listen to pointermove/pointerenter/pointerleave into a separate layer. rlayers 2.0.0+ can eliminate early feature layers that do not contain listeners for these events.

The RLayerBaseVector class is an abstract base component designed to be extended for specific vector layer types (e.g., RLayerVector, RLayerVectorTile). It provides common logic for managing an OpenLayers Vector source and handling feature-related events.

When using components derived from RLayerBaseVector, the component provides a RContext.Provider that makes the OpenLayers layer instance (ol), the source (source), and the component instance (rLayer) available to child components via React context. This allows nested <RFeature> components to access the layer and source automatically.

// Example conceptual usage of a component extending RLayerBaseVector
<RLayerVector 
  url="/api/features.json" 
  format={new GeoJSON()}
  onClick={(e) => console.log('Feature clicked:', e.feature)}
>
  {/* Nested RFeature components can now access the layer context */}
  <RFeature />
</RLayerVector>

This example demonstrates how to set up a basic map using OpenStreetMap, a vector layer, a styled feature, and an HTML overlay.

import React from 'react';
import {fromLonLat} from 'ol/proj';
import {Point} from 'ol/geom';
import 'ol/ol.css';

import {RMap, ROSM, RLayerVector, RFeature, ROverlay, RStyle} from 'rlayers';
import locationIcon from './svg/location.svg';

// Create a map, its size is set in the CSS class example-map
<RMap className='example-map' initial={{center: fromLonLat([2.364, 48.82]), zoom: 11}}>
    {/* Use an OpenStreetMap background */}
    <ROSM />
    {/* Create a single layer for holding vector features */}
    <RLayerVector zIndex={10}>
        {/* Create a style for rendering the features */}
        <RStyle.RStyle>
            {/* Consisting of a single icon, that is slightly offset
             * so that its center falls over the center of the feature */}
            <RStyle.RIcon src={locationIcon} anchor={[0.5, 0.8]} />
        </RStyle.RStyle>
        {/* Create a single feature in the vector layer */}
        <RFeature
            {/* Its geometry is a point geometry over the monument */}
            geometry={new Point(fromLonLat([2.295, 48.8737]))}
            {/* Bind an onClick handler */}
            onClick={(e) =>
                {/* e.map is the underlying OpenLayers map - we call getView().fit()
                    to pan/zoom the map over the monument with a small animation */}
                e.map.getView().fit(e.target.getGeometry().getExtent(), {
                    duration: 250,
                    maxZoom: 15
                })
            }
        >
            {/* The icon is an SVG image that represents the feature on the map
                while an overlay allows us to add a normal HTML element over the feature */}
            <ROverlay className='example-overlay'>
                Arc de Triomphe
                <br />
                <em>&#11017; click to zoom</em>
            </ROverlay>
        </RFeature>
    </RLayerVector>
</RMap>

You can access the raw OpenLayers objects through several methods:

1. useOL() hook: Retrieves the context object based on the current component's position in the tree. Available RContextType elements include:
   • map: Provided by a map (required for most components).
   • layer and source: Provided by all layers.
   • vectorlayer and vectorsource: Provided by vector layers (required for <RFeature>).
   • vectortilelayer: Provided by vector tile layers.
   • location and feature: Provided by a map feature (required for <ROverlay> and <RPopup>).
   • style: Provided by a style definition.
2. Event Handlers: In all event handlers, OpenLayers passes the target object in event.target and the map in event.map.
3. React Refs: Access objects outside of their context using React.RefObject. Every component has an .ol property containing the OpenLayers object. For layer objects, the underlying source is available via .source.

Example using Refs:

const layerRef = React.createRef() as React.RefObject<RLayerVector>;
// ... in render
<RLayerVector ref={layerRef} />
// ... later
const olLayer = layerRef.current.ol;
const olSource = layerRef.current.source;