vt-pbf

library3.1.3jsnpmunverified

vt-pbf is a JavaScript library for serializing Mapbox vector tiles into binary Protobuf format, adhering to the Mapbox Vector Tile Specification. It provides methods to convert both `vector-tile-js` objects and `geojson-vt` tile structures into a Protobuf buffer. The current stable version is 3.1.3. Releases appear to be driven by bug fixes and performance improvements, with a focus on specification compliance and encoding correctness for various GeoJSON types and property values, as seen with recent fixes for `null` value encoding. Its primary differentiator is its direct integration with Mapbox's ecosystem libraries like `geojson-vt` and `@mapbox/vector-tile` for efficient tile generation and manipulation, rather than being a generic Protobuf library.

serialization data

npm install vt-pbf

github ↗package ↗

INSTALL

IMPORT

SIG · VT-PBF

vt-pbf

serializationjavascriptv3.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

vtpbf

✓ import vtpbf from 'vt-pbf';

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

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

fromGeojsonVt

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

✗ import { fromGeojsonVt } from 'vt-pbf';

`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.

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);

Debug

Known issues

breakingThe 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.

affects: <3.1.2

gotchaThe 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.

affects: >=1.0.0

gotchaWhen 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 })`.

affects: >=2.0.0

Errors

Common errors & fixes

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

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

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.

Upgrade

Version history

3.1.3latest on npm

Audit

Dependencies

@mapbox/vector-tileoptionalUsed for parsing existing PBF data into a JS representation before serialization with vt-pbf, as shown in usage examples.

geojson-vtoptionalUsed for generating GeoJSON tiles which are then serialized by vt-pbf, as shown in usage examples.

pbfoptionalUsed internally by @mapbox/vector-tile and for handling Protobuf buffers.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mapbox/vt-pbf ↗

packagehttps://www.npmjs.com/package/vt-pbf ↗