MapLibre GL JS Custom Layers

A collection of custom layer implementations for MapLibre GL JS, with rendering cores extracted so the same logic can be reused through engine-specific adaptors.

Live Demos & Documentation

---

Packages

This monorepo contains the following packages:

Package	NPM Version	License	Description
@naivemap/map-gl-layer-adaptor	n/a		Shared adaptor contracts and helpers for MapLibre GL JS and Mapbox GL JS custom layers.
@naivemap/echarts-layer-core	n/a		Engine-agnostic ECharts layer runtime that can be hosted by different map adaptors.
@naivemap/image-layer-core	n/a		Engine-agnostic image layer runtime with projection warping and mask support.
@naivemap/maplibre-gl-echarts-layer			Integrates Apache ECharts (lines and scatter charts) as a high-performance layer in MapLibre GL JS.
@naivemap/maplibre-gl-image-layer			A versatile layer for displaying georeferenced images with various projections (using proj4js) on the map.
@naivemap/mapbox-gl-echarts-layer	n/a		Mapbox GL JS wrapper of the shared ECharts core runtime.
@naivemap/mapbox-gl-image-layer	n/a		Mapbox GL JS wrapper of the shared image core runtime.

Architecture

The repository now separates layer behavior into three tiers:

• core packages contain rendering logic and map-agnostic state management.
• adaptor helpers translate host engine lifecycle hooks into the core runtime contracts.
• product packages such as @naivemap/maplibre-gl-image-layer stay backwards compatible and act as thin MapLibre wrappers.

This makes it practical to add a Mapbox GL JS entry point without copying the rendering implementation.

Getting Started

Installation

Install the desired package using your favorite package manager:

# Install EChartsLayer
pnpm add @naivemap/maplibre-gl-echarts-layer echarts maplibre-gl

# Install ImageLayer
pnpm add @naivemap/maplibre-gl-image-layer proj4 maplibre-gl

# Install Mapbox EChartsLayer
pnpm add @naivemap/mapbox-gl-echarts-layer echarts mapbox-gl

# Install Mapbox ImageLayer
pnpm add @naivemap/mapbox-gl-image-layer proj4 mapbox-gl

Quick Usage Example (EChartsLayer)

Here is a quick example of how to use the @naivemap/maplibre-gl-echarts-layer.

import { Map } from 'maplibre-gl'
import EChartsLayer from '@naivemap/maplibre-gl-echarts-layer'

// 1. Initialize the map
const map = new Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 1
})

// 2. Define your ECharts options
const option = {
  series: [
    {
      type: 'scatter',
      name: 'Cities',
      data: [
        { name: 'New York', value: [-74.006, 40.7128] },
        { name: 'London', value: [-0.1278, 51.5074] },
        { name: 'Tokyo', value: [139.6917, 35.6895] }
      ],
      symbolSize: 10
    }
  ]
}

// 3. Add the layer to the map
map.on('load', () => {
  const layer = new EChartsLayer('echarts-layer', option)
  map.addLayer(layer)
})

For more detailed examples and API documentation, please visit our documentation site.

Development

This project is a monorepo managed by pnpm.

1. Clone the repository:

   git clone https://github.com/naivemap/maplibre-gl-layers.git
   cd maplibre-gl-layers

2. Install dependencies:

   pnpm install

3. Run the development server for documentation: This command will build the packages, generate TypeDoc documentation, and start the VitePress development server.

   pnpm docs:dev

4. Build all packages:

   pnpm build

License

This project is licensed under the MIT License - see the LICENSE file for details.