@simvector/maplibre-protocol

A lightweight, custom protocol handler for MapLibre GL JS that authenticates vector tile and map style requests against SimVector tile servers using session JWTs.

Built to eliminate the security risk of exposing static API keys in client-side applications.

Installation

npm install @simvector/maplibre-protocol maplibre-gl
# or
yarn add @simvector/maplibre-protocol maplibre-gl
# or
pnpm add @simvector/maplibre-protocol maplibre-gl

Note: maplibre-gl is a peer dependency.

Quick Start

Register the protocol with MapLibre before initializing your map instance. Supply a getToken callback that fetches a valid SimVector session JWT from your application's backend proxy.

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import { registerSimVectorProtocol } from '@simvector/maplibre-protocol';

// 1. Register the protocol
registerSimVectorProtocol(maplibregl, {
  getToken: async () => {
    // Call your backend endpoint where your server-side API key is stored
    const response = await fetch('/api/simvector/token', { method: 'POST' });
    if (!response.ok) {
      throw new Error('Failed to retrieve SimVector map session token');
    }
    const data = await response.json();
    return data.token; // Must return a valid JWT string
  },
});

// 2. Initialize the map as normal with anything calling SimVector leveraging the simvector:// protocol
const map = new maplibregl.Map({
  container: 'map',
  style: 'simvector://styles/aviation-dark-v1.json',
  center: [139.6917, 35.6895], // Tokyo
  zoom: 8,
});

How It Works

1. URL Rewriting: Any resource requested with simvector:// (e.g., simvector://globe/{z}/{x}/{y}.pbf) is rewritten to target https://tiles.simvector.net/globe/{z}/{x}/{y}.pbf.
2. Bearer Injection: Attaches the retrieved session JWT to the outgoing request via an Authorization: Bearer <JWT> header.
3. Smart Refreshing: If the tile server returns 401 Unauthorized, the protocol forces a fresh token retrieval via your getToken function and re-executes the tile request transparently.

API Reference

registerSimVectorProtocol(maplibregl, options)

Registers the protocol with your MapLibre GL JS library instance.

Parameters

| Parameter | Type | Description | | :--- | :--- | :--- | | maplibregl | object | The imported maplibre-gl instance. | | options | SimVectorProtocolOptions | Configuration options for the protocol handler. |

SimVectorProtocolOptions

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | getToken | () => Promise<string> | Required | Async callback that returns a valid SimVector JWT string from your application server. | | baseUrl | string | 'https://tiles.simvector.net' | Optional base URL for your SimVector tile host. | | protocolName | string | 'simvector' | Optional custom scheme name registered in MapLibre. |

License

MIT License.# simvector-maplibre-protocol