maps-core — Geolonia Mapsのコアライブラリ

Library
maps-core — Geolonia Mapsのコアライブラリ

maps-core — Geolonia Mapsのコアライブラリ

Geoloniaが公開する「maps-core」は、MapLibre GL JSを拡張してGeoloniaプラットフォームと連携するためのコアライブラリです。DOMに依存せず副作用を避ける設計により、maps-embedやmaps-reactといった上位パッケージの共通基盤として機能します。TypeScriptで型安全に実装され、maplibre-glをピア依存として利用することで柔軟かつ軽量に組み込めることが特徴です。（約300字）

https://github.com/geolonia/maps-core

概要

Geoloniaのmaps-coreは、MapLibre GL JS（オープンなMapbox GL互換ランタイム）を拡張し、Geoloniaプラットフォーム特有の統合点（タイル・スタイル・認証など）を共通で扱うためのコアライブラリです。設計方針として「副作用なし」「DOM非依存」を掲げ、サーバーサイドレンダリングや各種フレームワーク（React、プレーンJSなど）から安全に利用できる土台を提供します。TypeScriptで書かれており、maps-embed／maps-reactのような上位パッケージが依存して機能を組み立てられるモジュール群になっています。（約300字）

GitHub

リポジトリの統計情報

  • スター数: 2
  • フォーク数: 0
  • ウォッチャー数: 2
  • コミット数: 17
  • ファイル数: 15
  • メインの言語: TypeScript

主な特徴

  • MapLibre GL JS拡張: maplibre-glをピア依存として活用し、Geolonia向けの統合機能を追加。
  • DOM非依存・副作用なし: ライブラリ自体はレンダリング層に依存しないためSSRやテストが容易。
  • TypeScript採用: 型定義によりAPIの安全性と開発体験を向上。
  • 下位互換の基盤: maps-embedやmaps-reactなど複数のパッケージが共通で使えるように抽象化。

技術的なポイント

maps-coreは「表示ロジック」と「プラットフォーム統合」を分離することで汎用性を高めています。具体的には、MapLibre GL のインスタンス生成やスタイル適用のための薄いラッパー群を提供しつつ、Geolonia独自のタイルURL、認証トークン、デフォルトスタイルやCSS（READMEにcssのimport例あり）などの設定を注入できる仕組みになっています。副作用を避ける設計は、ライブラリ内部でDOMアクセスやグローバルな状態変更を行わないことを意味し、これによりReactコンポーネントやサーバーサイドの処理パイプライン上でも安全に再利用できます。TypeScript ベースで型宣言が整備されているため、ホストアプリケーション側での補完や静的チェックが効き、ライブラリの拡張やデバッグがしやすくなっています。さらに、maplibre-glをpeerDependencyにしているため、アプリ側がMapLibreのバージョン管理を握れ、バンドルサイズや互換性の調整が容易です。設計としては小さなコアに絞り、追加機能やUI層は上位パッケージに委ねる方針で、再利用性と保守性を両立しています。（約700字）

プロジェクトの構成

主要なファイルとディレクトリ：

  • .github: dir
  • .gitignore: file
  • LICENSE: file（ライセンス情報）
  • README.md: file（導入・利用例）
  • biome.json: file
  • package.json: file
  • src/: dir（TypeScriptソース）
  • css/: dir（パッケージで提供するCSS）
  • dist/ または lib/: dir（ビルド成果物がある場合）
  • tsconfig.json: file（TypeScript設定）
  • index.ts / main entry: file …他 10 ファイル

解説：

  • package.jsonにはmaplibre-glがpeerDependencyとして定義され、npmインストール時の注意点が記載されています（README）。これは、ライブラリ自体がMapLibreの具体実装に依存せず、ホスト側が任意のMapLibreバージョンを採用できるようにするためです。
  • srcディレクトリは、DOMに依存しないコアロジック（マップ初期化ヘルパー、スタイル/ソース設定、型定義、ユーティリティ関数）で構成されている想定です。上位レイヤー（maps-embed, maps-react）はここを利用してUIやDOMバインディングを追加します。
  • cssディレクトリにはREADMEサンプルが示すように、maplibre-glのスタイルに合わせた補助CSSが含まれているため、簡単に見た目の整合性をとることができます。
  • LICENSEファイルはリポジトリに含まれており、利用条件を確認してから組み込む必要があります。

READMEの抜粋と使い方のポイント

READMEでは導入手順が簡潔に示されており、npmでのインストール例（npm install @geolonia/maps-core maplibre-gl）と、maplibre-glのCSSおよびmaps-coreのCSSをimportする例が掲載されています。重要なポイントはmaplibre-glがpeer dependencyである点と、maps-core自体はDOM操作を行わないため、ReactやVanilla JS、サーバーサイドレンダリング環境など、様々な環境でラップして利用できることです。上位パッケージはこのコアを使って実際のDOM反映やイベントハンドリングを実装します。

まとめ

軽量で再利用しやすいGeoloniaマップの共通基盤。導入の自由度が高く拡張に向く設計。（約50字）

リポジトリ情報：

READMEの抜粋：

@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.

Usage

import 'maplibre-gl/dist/maplibre-gl.css';
import '@geolonia/maps-core/css';
im...