English | 日本語 | Español (Latinoamérica)

@mapconductor/react-for-maplibre

MapLibre GL JS provider for the MapConductor React SDK. Renders a MapLibre map through MapConductor's provider-independent camera, marker, and overlay API, so the same application code can also run on Google Maps, Mapbox, Leaflet, OpenLayers, ArcGIS, Cesium, or HERE.

Installation

npm install @mapconductor/react-for-maplibre

@mapconductor/js-sdk-core and @mapconductor/js-sdk-react (used for markers and other shared components) are installed automatically as dependencies. Your code imports from both directly, so with pnpm's strict (isolated) node_modules — or whenever you prefer to declare everything you import — install them explicitly instead:

npm install @mapconductor/react-for-maplibre @mapconductor/js-sdk-core @mapconductor/js-sdk-react

maplibre-gl (v6) is bundled as a dependency; no API key is required for the built-in OpenStreetMap Japan styles.

Web Worker (MapLibre GL JS v6)

Nothing to set up. MapLibre GL JS v6 loads its Web Worker from a URL that no bundler can resolve on its own, so this package ships a self-contained build of that worker and registers it when the first map is created.

This holds for Vite and webpack/Rspack alike, in dev and in production builds.

One exception: serving the worker from your own URL — a shared CDN, or a build that already emits it. Call setMapLibreWorkerUrl(url) before the first map; the bundled worker is then skipped and never downloaded.

Vite's dev server runs the bundled worker through its transform pipeline, which injects a /@vite/client import and inflates the file (~478 KB to ~2.8 MB). That is noisy but harmless — the worker still runs. Production builds emit it as a plain asset.

If the worker fails to load, MapLibre does not raise an error — the map renders its background and no tiles ever arrive. A network panel with zero .pbf requests is the symptom to look for.

Hello Map tutorial

The simplest possible map app, built with MapConductor + MapLibre: click the marker and a "Hello, MapConductor" bubble pops up. You can build it in the 5 steps below. It uses MapLibre, which needs no API key, so you can copy-paste and it just works.

Step 1: Create a React project

Create a React + TypeScript project with Vite.

npm create vite@latest hello-map -- --template react-ts
cd hello-map
npm install
npm run dev

Step 2: Install MapConductor (MapLibre)

Install the package needed to show a map. We use MapLibre here, but you can use other map modules too.

npm install @mapconductor/react-for-maplibre

• @mapconductor/react-for-maplibre — components / hooks for MapLibre
• @mapconductor/js-sdk-react / @mapconductor/js-sdk-core are installed automatically as dependencies.

Step 3: Show the map

Create the map state with useMapLibreViewState and render it with <MapLibreMapView>. Don't forget the style CSS import. Give the outer element a height to make it full-screen.

import {
  MapLibreDesign,
  MapLibreMapView,
  useMapLibreViewState,
} from '@mapconductor/react-for-maplibre';
import '@mapconductor/react-for-maplibre/style.css';
import { createGeoPoint, createMapCameraPosition } from '@mapconductor/js-sdk-core';

const TOKYO = createGeoPoint({ latitude: 35.6812, longitude: 139.7671 });
const INITIAL_CAMERA = createMapCameraPosition({ position: TOKYO, zoom: 14 });

export default function App() {
  const mapViewState = useMapLibreViewState({
    mapDesignType: MapLibreDesign.OsmBright,
    cameraPosition: INITIAL_CAMERA,
  });

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <MapLibreMapView state={mapViewState} />
    </div>
  );
}

Step 4: Place a marker

Create the marker state with createMarkerState and register it with <Marker>. Write overlays as child elements of the map component.

import { useMemo } from 'react';
import { createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';

// ...inside App...
const marker = useMemo(
  () => createMarkerState({ id: 'hello', position: TOKYO }),
  [],
);

// ...inside return...
<MapLibreMapView state={mapViewState}>
  <Marker state={marker} />
</MapLibreMapView>

Step 5: Show an InfoBubble on click

Track the selected state with useState, set it to true in the marker's onClick, and render <InfoBubble> only while selected. This is the finished app.

import { useMemo, useState } from 'react';
import {
  MapLibreDesign,
  MapLibreMapView,
  useMapLibreViewState,
} from '@mapconductor/react-for-maplibre';
import '@mapconductor/react-for-maplibre/style.css';
import {
  createGeoPoint,
  createMapCameraPosition,
  createMarkerState,
} from '@mapconductor/js-sdk-core';
import { InfoBubble, Marker } from '@mapconductor/js-sdk-react';

const TOKYO = createGeoPoint({ latitude: 35.6812, longitude: 139.7671 });
const INITIAL_CAMERA = createMapCameraPosition({ position: TOKYO, zoom: 14 });

export default function App() {
  const mapViewState = useMapLibreViewState({
    mapDesignType: MapLibreDesign.OsmBright,
    cameraPosition: INITIAL_CAMERA,
  });

  const [selected, setSelected] = useState(false);

  const marker = useMemo(
    () => createMarkerState({
      id: 'hello',
      position: TOKYO,
      onClick: () => setSelected(true),
    }),
    [],
  );

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <MapLibreMapView state={mapViewState} onMapClick={() => setSelected(false)}>
        <Marker state={marker} />
        {selected && (
          <InfoBubble marker={marker}>
            <div style={{ padding: '8px 12px', fontWeight: 600 }}>
              Hello, MapConductor
            </div>
          </InfoBubble>
        )}
      </MapLibreMapView>
    </div>
  );
}

Key points

• Coordinates, cameras and markers are created with js-sdk-core functions (provider-independent).
• The map component and hooks come from react-for-maplibre (provider-specific).
• Write overlays as child elements of the map component.
• Control show / hide with React useState.

Related packages

• @mapconductor/js-sdk-core — geometry, camera, and state primitives
• @mapconductor/js-sdk-react — shared Marker, Markers, shapes, and info bubbles