@geolonia/maps-core

Core library for Geolonia Maps. Extends MapLibre GL JS with Geolonia Maps platform integration.

Designed to be side-effect-free and DOM-independent, serving as the shared foundation for downstream packages such as maps-embed and maps-react.

Install

npm install @geolonia/maps-core maplibre-gl

maplibre-gl is a peer dependency. v6.x is required (^6.0.0).

This package is ESM-only, following MapLibre GL JS v6. There is no require() entry point. If you need a script-tag build, use the UMD bundle attached to each GitHub Release — it is self-contained and needs no worker setup. It does run its worker from a Blob URL, so a page with a Content-Security-Policy needs worker-src blob:.

Worker setup

MapLibre GL JS v6 ships ESM-only and loads its worker from a real URL resolved against import.meta.url. Most bundlers do not carry that file over on their own, so the map silently never finishes loading unless you point MapLibre at the worker yourself. Do this once, before the first map is created.

Two files are involved, not one: maplibre-gl-worker.mjs is a small shim that imports ./maplibre-gl-shared.mjs as a sibling. That splits the setups in two. Run the worker through the bundler's own worker pipeline and it comes out as a self-contained chunk, with nothing else to place. Copy or serve the shim verbatim instead, and the sibling has to sit next to it in the output — miss it and the worker dies on its first import, with no exception and no console error.

Vite has such a pipeline, and ?worker&url is what routes the file through it:

// Vite
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import { setWorkerUrl } from 'maplibre-gl';

setWorkerUrl(workerUrl);

Plain ?url is not enough — it emits the shim verbatim, which puts you in the second case without the sibling.

webpack is in that second case: copy both files into the output and point at the copy. Note that new URL('maplibre-gl/dist/maplibre-gl-worker.mjs', import.meta.url) does not work — webpack emits the shim on its own, leaving the sibling import to 404.

npm install --save-dev copy-webpack-plugin

// webpack.config.js
const CopyPlugin = require('copy-webpack-plugin');

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: require.resolve('maplibre-gl/dist/maplibre-gl-worker.mjs'),
          to: 'maplibre-gl-worker.mjs',
        },
        {
          from: require.resolve('maplibre-gl/dist/maplibre-gl-shared.mjs'),
          to: 'maplibre-gl-shared.mjs',
        },
      ],
    }),
  ],
};

import { setWorkerUrl } from 'maplibre-gl';

setWorkerUrl('maplibre-gl-worker.mjs');

For esbuild, Rollup and Turbopack, see the MapLibre docs — and work out which of the two cases above your setup lands in.

Loading MapLibre from a CDN as an ES module needs no setup: the worker URL is derived from the module's own URL. Cross-origin, MapLibre starts that worker from a same-origin Blob URL, so the page needs worker-src blob:. If your CSP cannot allow that, host the two worker files yourself and name the worker explicitly before creating a map:

import { setWorkerUrl } from 'maplibre-gl';

setWorkerUrl('/path/to/maplibre-gl-worker.mjs');

Usage

import 'maplibre-gl/dist/maplibre-gl.css';
import '@geolonia/maps-core/css';
import { GeoloniaMap } from '@geolonia/maps-core';

const map = new GeoloniaMap({
  container: '#map',
  apiKey: 'YOUR-API-KEY',
  style: 'geolonia/basic-v2',
  center: [139.7671, 35.6812],
  zoom: 14,
});

Using External Styles Without API Key

const map = new GeoloniaMap({
  container: '#map',
  style: 'https://tile.openstreetmap.jp/styles/osm-bright/style.json',
  center: [139.7671, 35.6812],
  zoom: 14,
});

Geolonia API key is only required when using Geolonia's hosted styles and tiles.

API

GeoloniaMap

Extends maplibregl.Map. Accepts GeoloniaMapOptions.

const map = new GeoloniaMap({
  container: '#map',           // HTMLElement or CSS selector
  apiKey: 'YOUR-API-KEY',      // Geolonia API key
  style: 'geolonia/basic-v2',  // Style name or URL
  center: [139.77, 35.68],     // [lng, lat]
  zoom: 12,

  // All optional
  lang: 'auto',                 // 'ja' | 'en' | 'auto'
  stage: 'v1',                  // 'dev' | 'v1'
  marker: true,                 // Show default marker at center
  markerColor: '#E4402F',
  openPopup: false,             // Auto-open marker popup
  customMarker: '#my-marker',   // CSS selector for custom marker element
  customMarkerOffset: [0, -15],
  loader: true,                 // Loading animation
  gestureHandling: true,        // Gesture control on scrollable pages
  navigationControl: true,      // true | false | 'top-right' etc.
  geolocateControl: false,
  fullscreenControl: false,
  scaleControl: false,
  geoloniaControl: true,        // Geolonia logo
  geojson: 'https://example.com/data.geojson',
  cluster: true,
  clusterColor: '#ff0000',
  choropleth: 'value',          // Color polygons by a property (see below)
  heatmap: 'weight',            // Draw points as a heatmap (see below)
  circle: { size: 'weight', color: 'category' }, // Size and color points (see below)
  simpleVector: 'my-tileset',   // Vector tile URL or tileset ID
  '3d': false,
  errorMessage: undefined,      // Message shown when the map fails to initialize
});

errorMessage

When the map cannot be initialized (typically because WebGL is unavailable on the device), the container is replaced with a message telling the visitor what to try: restart the browser, restart the device, try another browser, update the graphics driver, and contact the site owner if it still fails. The message is shortened, and finally reduced to the headline alone, as the map container gets smaller.

Pass errorMessage to take that over:

// Replace the wording. The value is rendered as plain text, not as HTML.
new GeoloniaMap({ container: '#map', errorMessage: 'Sorry, the map is unavailable.' });

// Show nothing at all, e.g. when the page renders its own fallback.
new GeoloniaMap({ container: '#map', errorMessage: false });

choropleth, heatmap and circle

Style the geojson data by the values of its properties, without writing MapLibre expressions.

// Color polygons by `value`. The range defaults to the min and max of the data.
new GeoloniaMap({ container: '#map', geojson, choropleth: 'value' });
new GeoloniaMap({
  container: '#map',
  geojson,
  choropleth: { property: 'value', colors: ['#FFF2CC', '#B3261E'], range: [0, 100] },
});

// Draw points as a heatmap. `true` weights every point equally.
new GeoloniaMap({ container: '#map', geojson, heatmap: 'weight' });

// Size points by `weight` and color them by `category`.
// Numeric values get a color ramp, other values one color per category.
new GeoloniaMap({ container: '#map', geojson, circle: { size: 'weight', color: 'category' } });

• These options take precedence over simplestyle properties such as fill and marker-color. Features without a numeric value fall back to the simplestyle look.
• heatmap and circle turn clustering off. heatmap also hides the point markers. circle draws every point as a circle, including points with marker-symbol, and hides the icons and titles.
• The range and categories are computed again when the GeoJSON is loaded from a URL or replaced with updateData().
• colors is optional. The defaults are Geolonia's orange ramp and a categorical palette.
• With choropleth, polygons without a fill-opacity property are drawn at 0.7 opacity instead of 1, so that the base map shows through.
• With circle.color, a property is treated as numeric only when every value is a number. Numeric strings such as "12" count as categories. Objects and arrays are not colored.

transformRequest

Works like MapLibre's transformRequest, and is also called for the requests that maps-core rewrites itself: Geolonia sources (api.geolonia.com and the Geolonia tile hosts) and Geolonia sprites. For those, the function receives the URL after maps-core has added key and sessionId, so the parameters are kept as long as you build on the URL you are given.

• Return a RequestParameters object to use it as is.
• Return undefined to keep the request maps-core built.
• A Promise may be returned. If it resolves to undefined, the request maps-core built is used.

new GeoloniaMap({
  container: '#map',
  transformRequest: (url, resourceType) => {
    // Load another tileset from the Geolonia tile server
    if (resourceType === 'Source' && url.includes('tileserver.geolonia.com/oneself/')) {
      return { url: url.replace('/oneself/', '/my-tileset/') };
    }
    return undefined;
  },
});

Replacing the function later with map.setTransformRequest() also removes the maps-core rewriting, including key and sessionId.

GeoloniaMarker

Extends maplibregl.Marker with Geolonia's default marker style.

import { GeoloniaMarker } from '@geolonia/maps-core';

new GeoloniaMarker({ color: '#0066FF' })
  .setLngLat([139.77, 35.68])
  .addTo(map);

SimpleStyle

GeoJSON visualization based on simplestyle-spec.

import { SimpleStyle } from '@geolonia/maps-core';

const ss = new SimpleStyle(geojson, { cluster: true });
// Also accepts `choropleth`, `heatmap` and `circle` (see GeoloniaMap options)
ss.addTo(map).fitBounds();

keyring

API key and stage management.

import { keyring } from '@geolonia/maps-core';

keyring.setApiKey('YOUR-API-KEY');
keyring.setStage('v1');

Related Packages

Package	Description
@geolonia/maps-embed	HTML data-* attribute map embedding
@geolonia/maps-react	React components

Development

npm install
npm run build     # ESM + DTS
npm run test      # Vitest unit tests
npm run build:umd # UMD bundle (dist/umd/), required by e2e/umd.spec.ts
npm run e2e       # Playwright E2E tests
npm run lint      # Biome
npm run dev       # Vite dev server (example/)

License

MIT