MapLibre GL
Installation
If you're reading tiles from a Protomaps CDN deployment, your tile source is just a normal source
defined in a MapLibre GL style.
{ "sources": { "protomaps": { "type": "vector", "tiles": ["https://mycdn.com/tileset/{z}/{x}/{y}.mvt"], "minzoom": 0, "maxzoom": 10 } } }
For reading PMTiles directly from cloud storage, you'll need the pmtiles
JavaScript library.
The JavaScript library includes a plugin for MapLibre GL that uses its addProtocol
feature.
npm install pmtiles
import * as pmtiles from "pmtiles";
let protocol = new pmtiles.Protocol(); maplibregl.addProtocol("pmtiles",protocol.tile);
{ "sources": { "protomaps": { "type": "vector", "url": "pmtiles://https://example.com/example.pmtiles", } } }
Using the pmtiles://
protocol will automatically derive a minzoom
and maxzoom
for your Source
.
React
addProtocol
works best if it is only called once in the lifecycle of your application. A way to accomplish this in React is with a hook like this at the root component:
import maplibregl from 'maplibre-gl'; import { Protocol } from 'pmtiles'; ... useEffect(() => { let protocol = new Protocol(); maplibregl.addProtocol("pmtiles",protocol.tile); return () => { maplibregl.removeProtocol("pmtiles"); } }, []);
See this CodeSandbox example for a minimal working setup.
Vector Basemaps
Examples of JSON themes for MapLibre GL will appear in the basemaps repository.
The protomaps-themes-base
NPM module contains basemap layer definitions compatible with OpenStreetMap downloads from Protomaps.
npm install protomaps-themes-base
import layers from 'protomaps-themes-base';
style: { version:8, glyphs:'https://cdn.protomaps.com/fonts/pbf/{fontstack}/{range}.pbf', sources: { "protomaps": { type: "vector", url: "...", attribution: '<a href="https://protomaps.com">Protomaps</a> © <a href="https://openstreetmap.org">OpenStreetMap</a>' } }, layers: layers("protomaps","light") }
the default export from protomaps-themes-base
is a function that takes 2 arguments:
the source name of the basemap.
the theme, one of
light
,dark
,white
,black
,grayscale
ordebug
.
Raster or Terrain PMTiles
For raster tiles you'll just need to change the type
of your source to raster
:
{ "sources": { "protomaps": { "type": "raster", "url": "pmtiles://https://example.com/example.pmtiles", } } }
Protomaps also distributes terrain tilesets in the Terrarium RGB encoding. These have a special source type in MapLibre GL:
{ "sources": { "protomaps": { "type": "raster-dem", "url": "pmtiles://https://example.com/example.pmtiles", "encoding": "terrarium" } } }