{"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,"search_vec":"'3.1.3':55 'adher':22 'appear':57 'binari':19 'buffer':49 'bug':62 'complianc':72 'convert':33 'correct':75 'current':51 'differenti':94 'direct':97 'driven':60 'ecosystem':102 'effici':111 'encod':74,91 'fix':63,87 'focus':69 'format':21 'generat':113 'generic':120 'geojson':42,78,106 'geojson-vt':41,105 'improv':66 'integr':98 'javascript':11,123 'js':38 'librari':12,103,122 'like':104 'manipul':115 'mapbox':1,15,25,100 'mapbox/vector-tile':109 'method':31 'null':89 'object':39 'pbf':8 'perform':65 'primari':93 'properti':81 'protobuf':4,20,48,121 'provid':30 'rather':116 'recent':86 'releas':56 'seen':84 'serial':5,14 'specif':28,71 'stabl':52 'structur':45 'tile':3,17,27,37,44,112 'type':79 'valu':82,90 'various':77 'vector':2,16,26,36 'vector-tile-j':35 'version':53 'vt':7,43,107 'vt-pbf':6","created_at":"2026-04-19T13:42:56.411424+00:00","updated_at":"2026-04-19T13:42:56.411424+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/mapbox/vt-pbf","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vt-pbf","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}