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 or debug.

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"
		}
	}
}