Mapbox Vector Tile Protobuf Serializer

Common errors

• TypeError: Cannot read properties of undefined (reading 'features')

  cause Attempting to pass a raw GeoJSON object directly to `vtpbf` or `vtpbf.fromGeojsonVt` without first processing it through `geojson-vt` or `vector-tile-js`.
  fix Use `geojsonVt(yourGeoJson).getTile(z, x, y)` to obtain a tile object, then pass that to `vtpbf.fromGeojsonVt`.

• Error: Unknown geometry type: X

  cause The input tile object contains a GeoJSON geometry type that is not supported by the Mapbox Vector Tile specification or `vt-pbf`'s encoder.
  fix Ensure your GeoJSON data only contains Point, LineString, and Polygon geometry types. Multi-part geometries are generally supported but complex or non-standard types will fail.

Warnings

• breaking The encoding of `null` property values was fixed in v3.1.2 and further refined in v3.1.3 to strictly conform to the Mapbox Vector Tile specification. Older versions might have encoded `null` values incorrectly, leading to non-compliant or incompatible PBFs.
  Fix: Upgrade to `vt-pbf@^3.1.3` to ensure correct and spec-compliant handling of `null` property values.
• gotcha The library expects specific input formats depending on the source: either a `VectorTile` instance from `@mapbox/vector-tile` or a tile object generated by `geojson-vt`. Directly passing raw GeoJSON or other arbitrary structures will result in errors.
  Fix: Ensure input data is correctly pre-processed by either `@mapbox/vector-tile` (for reading PBFs) or `geojson-vt` (for converting GeoJSON to tiles) before passing to `vtpbf` or `vtpbf.fromGeojsonVt` respectively.
• gotcha When using `vtpbf.fromGeojsonVt`, the `options` argument allows specifying `version` and `extent`. Failing to set these correctly might lead to PBFs that do not match the intended Mapbox Vector Tile specification version or coordinate system extent, causing rendering issues in clients.
  Fix: Always explicitly set `version` (defaults to 1) and `extent` (defaults to 4096) in the options object if your target MVT specification or tile system requires non-default values: `vtpbf.fromGeojsonVt(layerMap, { version: 2, extent: 8192 })`.

Install

• npm install vt-pbf npm
• yarn add vt-pbf yarn
• pnpm add vt-pbf pnpm

Imports

• vtpbf
  wrong:

  const vtpbf = require('vt-pbf');

  correct:

  import vtpbf from 'vt-pbf';

  While the README shows CommonJS `require`, modern Node.js and browser environments should prefer ESM `import`. The library is dual-published.
• fromGeojsonVt
  wrong:

  import { fromGeojsonVt } from 'vt-pbf';

  correct:

  import vtpbf from 'vt-pbf';
  const buff = vtpbf.fromGeojsonVt({ 'layer': tile });

  `fromGeojsonVt` is a named property on the default export `vtpbf`, not a named export itself.
• vtpbf as vtSerializer

  import vtSerializer from 'vt-pbf';

  Useful for avoiding naming conflicts or when preferring a more descriptive local name for the default export.

Quickstart

Demonstrates how to use `vt-pbf` to serialize a GeoJSON object (processed by `geojson-vt`) into a binary Mapbox Vector Tile Protobuf (.pbf) file, including recent `null` value handling.

import vtpbf from 'vt-pbf';
import geojsonVt from 'geojson-vt';
import fs from 'node:fs';

const sampleGeoJSON = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "name": "Example Polygon", "value": null },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[-10, -10], [10, -10], [10, 10], [-10, 10], [-10, -10]]]
      }
    }
  ]
};

async function serializeGeoJsonToPbf() {
  // Generate a tile index from GeoJSON
  const tileindex = geojsonVt(sampleGeoJSON, { maxZoom: 14 });

  // Get a specific tile (e.g., zoom 0, x 0, y 0)
  const tile = tileindex.getTile(0, 0, 0);

  if (tile) {
    // Serialize the geojson-vt tile object into a PBF buffer
    const buffer = vtpbf.fromGeojsonVt({ 'myLayer': tile }, { version: 2, extent: 4096 });

    // Write the buffer to a file
    const filePath = './my-serialized-tile.pbf';
    fs.writeFileSync(filePath, buffer);
    console.log(`Successfully wrote PBF tile to ${filePath}. File size: ${buffer.byteLength} bytes`);
  } else {
    console.log('No tile found for the specified coordinates.');
  }
}

serializeGeoJsonToPbf().catch(console.error);