{"id":12393,"library":"vt-pbf","title":"Mapbox Vector Tile Protobuf Serializer","description":"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.","status":"active","version":"3.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/mapbox/vt-pbf","tags":["javascript"],"install":[{"cmd":"npm install vt-pbf","lang":"bash","label":"npm"},{"cmd":"yarn add vt-pbf","lang":"bash","label":"yarn"},{"cmd":"pnpm add vt-pbf","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for parsing existing PBF data into a JS representation before serialization with vt-pbf, as shown in usage examples.","package":"@mapbox/vector-tile","optional":true},{"reason":"Used for generating GeoJSON tiles which are then serialized by vt-pbf, as shown in usage examples.","package":"geojson-vt","optional":true},{"reason":"Used internally by @mapbox/vector-tile and for handling Protobuf buffers.","package":"pbf","optional":true}],"imports":[{"note":"While the README shows CommonJS `require`, modern Node.js and browser environments should prefer ESM `import`. The library is dual-published.","wrong":"const vtpbf = require('vt-pbf');","symbol":"vtpbf","correct":"import vtpbf from 'vt-pbf';"},{"note":"`fromGeojsonVt` is a named property on the default export `vtpbf`, not a named export itself.","wrong":"import { fromGeojsonVt } from 'vt-pbf';","symbol":"fromGeojsonVt","correct":"import vtpbf from 'vt-pbf';\nconst buff = vtpbf.fromGeojsonVt({ 'layer': tile });"},{"note":"Useful for avoiding naming conflicts or when preferring a more descriptive local name for the default export.","symbol":"vtpbf as vtSerializer","correct":"import vtSerializer from 'vt-pbf';"}],"quickstart":{"code":"import vtpbf from 'vt-pbf';\nimport geojsonVt from 'geojson-vt';\nimport fs from 'node:fs';\n\nconst sampleGeoJSON = {\n  \"type\": \"FeatureCollection\",\n  \"features\": [\n    {\n      \"type\": \"Feature\",\n      \"properties\": { \"name\": \"Example Polygon\", \"value\": null },\n      \"geometry\": {\n        \"type\": \"Polygon\",\n        \"coordinates\": [[[-10, -10], [10, -10], [10, 10], [-10, 10], [-10, -10]]]\n      }\n    }\n  ]\n};\n\nasync function serializeGeoJsonToPbf() {\n  // Generate a tile index from GeoJSON\n  const tileindex = geojsonVt(sampleGeoJSON, { maxZoom: 14 });\n\n  // Get a specific tile (e.g., zoom 0, x 0, y 0)\n  const tile = tileindex.getTile(0, 0, 0);\n\n  if (tile) {\n    // Serialize the geojson-vt tile object into a PBF buffer\n    const buffer = vtpbf.fromGeojsonVt({ 'myLayer': tile }, { version: 2, extent: 4096 });\n\n    // Write the buffer to a file\n    const filePath = './my-serialized-tile.pbf';\n    fs.writeFileSync(filePath, buffer);\n    console.log(`Successfully wrote PBF tile to ${filePath}. File size: ${buffer.byteLength} bytes`);\n  } else {\n    console.log('No tile found for the specified coordinates.');\n  }\n}\n\nserializeGeoJsonToPbf().catch(console.error);","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade to `vt-pbf@^3.1.3` to ensure correct and spec-compliant handling of `null` property values.","message":"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.","severity":"breaking","affected_versions":"<3.1.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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 })`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `geojsonVt(yourGeoJson).getTile(z, x, y)` to obtain a tile object, then pass that to `vtpbf.fromGeojsonVt`.","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`.","error":"TypeError: Cannot read properties of undefined (reading 'features')"},{"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.","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.","error":"Error: Unknown geometry type: X"}],"ecosystem":"npm"}