---
title: "PMTiles"
description: "Register the pmtiles:// protocol to use a single .pmtiles file as a vector or raster tile source."
canonical_url: "https://maplibre.mhaibaraai.cn/en/docs/extensions/pmtiles"
---
# PMTiles

> Register the pmtiles:// protocol to use a single .pmtiles file as a vector or raster tile source.

## Introduction

[PMTiles](https://docs.protomaps.com/pmtiles/) packs a whole tileset into one file that the browser reads on demand with HTTP range requests, so no tile server is needed. Once the `pmtiles://` protocol is registered, write a `pmtiles://` address as the `url` of `MaplibreSource` or `MaplibreRasterLayer`.

> [!NOTE]
> 
> Requires the optional dependency 
> 
> pmtiles
> 
> , and the file host must support range requests and CORS.

## Register the protocol

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@movk/maplibre'],
  maplibre: {
    protocols: { pmtiles: true }
  }
})
```

```ts [main.ts (Vue + Vite)]
import { registerPmtilesProtocol } from '@movk/maplibre/utils/pmtiles'

// Register synchronously before the first map is created; repeated calls register once
registerPmtilesProtocol()
```

`registerPmtilesProtocol` returns the `Protocol` instance, so you can register custom sources (such as local files) with `protocol.add(new PMTiles(source))`.

## Usage

```vue [PmtilesExample.vue]
<script setup lang="ts">
import type { VectorSourceSpecification } from '@maplibre/maplibre-gl-style-spec'

// Protomaps 公开 demo：佛罗伦萨矢量瓦片单文件
const source: VectorSourceSpecification = {
  type: 'vector',
  url: 'pmtiles://https://pmtiles.io/protomaps(vector)ODbL_firenze.pmtiles',
  attribution: '© OpenStreetMap contributors, Protomaps'
}
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ center: [11.255, 43.77], zoom: 13 }">
      <MaplibreSource source-id="firenze" :source="source">
        <MaplibreLayer
          layer-id="firenze-water"
          type="fill"
          source="firenze"
          source-layer="water"
          :paint="{ 'fill-color': '#93c5fd' }"
        />
        <MaplibreLayer
          layer-id="firenze-buildings"
          type="fill"
          source="firenze"
          source-layer="buildings"
          :paint="{ 'fill-color': '#d6d3d1' }"
        />
        <MaplibreLayer
          layer-id="firenze-roads"
          type="line"
          source="firenze"
          source-layer="roads"
          :paint="{ 'line-color': '#78716c', 'line-width': 1 }"
        />
      </MaplibreSource>
    </MaplibreMap>
  </div>
</template>
```

## Changelog

See commit history for [src/runtime/utils/pMTiles.ts](https://github.com/mhaibaraai/movk-maplibre/commits/main/src/runtime/utils/pMTiles.ts).


## Sitemap

See the full [sitemap](https://maplibre.mhaibaraai.cn/sitemap.md) for all pages.