pmtiles-protocol

This package makes it easy to work with Protomaps PMTiles directly in the browser. It provides fetch and XMLHttpRequest versions that support urls starting with pmtiles://, returning the respective TileJSON or tiles. It is meant to be used in browser applications.

Supported URLs

TileJSON

• pmtiles://https://example.com/path/to/mytiles.pmtiles (absolute)
• pmtiles://path/to/mytiles.pmtiles (relative to window.location.href)

Tiles

• pmtiles://https://example.com/path/to/mytiles.pmtiles/{z}/{x}/{y}.mvt (absolute)
• pmtiles://path/to/mytiles.pmtiles/{z}/{x}/{y}.mvt (relative to window.location.href)

How to use

The global overrides for fetch() and XMLHttpRequest are the easiest way to use pmtiles-protocol:

1import { register } from 'pmtiles-protocol';
2
3const unregister = register();

Now every request url that starts with pmtiles:// for anything in your web application that uses fetch() or XMLHttpRequest will go through pmtiles.

To restore the original global fetch() and XMLHttpRequest versions, call

1unregister();

If global overrides are not desired, pmtiles-protocol also provides a dedicated fetch() function and a dedicated XMLHttpRequest replacement:

1import { fetch, XMLHttpRequest } from 'pmtiles-protocol';

Examples

fetch

1fetch('pmtiles://https://example.com/mytiles.pmtiles/0/0/0.mvt');

fetches the 0/0/0 tile from the PMTiles file at https://example.com/mytiles.pmtiles.

XMLHttpRequest

1const xhr = new XMLHttpRequest();
2xhr.open('GET', 'pmtiles://path/to/mytiles.pmtiles');
3xhr.onload = () => {
4  console.log('TileJSON', xhr.responseText);
5};

logs the TileJSON from the PMTiles file at path/to/mytiles.pmtiles (relative to window.location.href) to the console.

In a Mapbox Style document

The pmtiles source below will use the TileJSON and tiles from https://example.com/mytiles.pmtiles:

1{
2  "sources": {
3    "pmtiles": {
4      "type": "vector",
5      "url": "pmtiles://https://example.com/mytiles.pmtiles"
6    }
7  }
8}

Limitations

This package won't add support for PMTiles when loading images by simply setting the src of an Image or HTTPImageElement. However, using an object url, the following would work:

1const img = new Image();
2fetch('pmtiles://path/to/mytiles.pmtiles/0/0/0.png')
3  .then((response) => response.blob())
4  .then((blob) => {
5    const objectUrl = URL.createObjectURL(blob);
6    img.onload = () => {
7      console.log('Image loaded');
8      URL.revokeObjectURL(objectUrl);
9    };
10    img.onerror = () => {
11      console.error('Image load error');
12      URL.revokeObjectURL(objectUrl);
13    };
14    img.src = objectUrl;
15  })
16  .catch((error) => {
17    console.error('Fetch error:', error);
18  });

fetch()

No known limitations.

XMLHttpRequest

The limitations below only apply when XMLHttpRequest is used with a pmtiles:// url.

• Only the load and error events are fired.
• The only methods that act on the PMTiles file are open() and send().
• Only the response and responseText properties are supported.
• Only the 200 and 404 status codes are used.