pbf

library0.2.0jsnpmunverified

PBF is a low-level, fast, and ultra-lightweight JavaScript library (3KB gzipped) for efficiently decoding and encoding Protocol Buffers (protobuf), a compact binary format for structured data serialization. Version 4.0.1 is the current stable release, which includes minor fixes building upon the significant 4.0.0 overhaul. The library is actively maintained, with a recent major release focusing on modernizing the codebase and developer experience. A key differentiator of PBF is its exceptional performance, consistently outperforming `JSON.parse`/`JSON.stringify` and other protobuf implementations like `protocol-buffers` in benchmarks. It supports lazy decoding and offers extensive customization options for reading and writing data, making it suitable for both Node.js and browser environments where performance and bundle size are critical considerations.

serialization data

npm install pbf

github ↗package ↗

INSTALL

IMPORT

SIG · PBF

pbf

serializationjavascriptv0.2.0

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.

Pbf

✓ import Pbf from 'pbf';

✗ const Pbf = require('pbf');

Since v4.0.0, PBF is an ES module and should be imported using ES module syntax. Direct CommonJS `require()` is no longer supported.

{ readMyMessage, writeMyMessage } (generated code)

✓ import { readMyMessage, writeMyMessage } from './my-schema.js';

✗ const { readMyMessage, writeMyMessage } = require('./my-schema');

PBF's code generation (CLI tool) defaults to ES modules since v4.0.0. Generated files use named exports and should be imported with ES module syntax. The `--legacy` flag is required for CommonJS output.

compile

✓ import { compile } from 'pbf/compile';

✗ const { compile } = require('pbf/compile');

The `compile` utility for runtime schema compilation is also an ES module and should be imported directly from its subpath using ES module syntax.

Demonstrates manual encoding and decoding of a custom data structure using PBF's low-level API without a .proto schema, showcasing its `writeField`, `readField`, and `readMessage` methods.

import Pbf from 'pbf'; interface MyComplexData { name: string; version: number; layer: { name: string; size: number; }; } function writeLayer(layer: MyComplexData['layer'], pbf: Pbf) { pbf.writeStringField(1, layer.name); pbf.writeVarintField(3, layer.size); } function writeData(data: MyComplexData, pbf: Pbf) { pbf.writeStringField(1, data.name); pbf.writeVarintField(2, data.version); pbf.writeMessage(3, writeLayer, data.layer); } function readLayer(tag: number, layer: MyComplexData['layer'], pbf: Pbf) { if (tag === 1) layer.name = pbf.readString(); else if (tag === 3) layer.size = pbf.readVarint(); } function readData(tag: number, data: MyComplexData, pbf: Pbf) { if (tag === 1) data.name = pbf.readString(); else if (tag === 2) data.version = pbf.readVarint(); else if (tag === 3) data.layer = pbf.readMessage(readLayer, {} as MyComplexData['layer']); } const myData: MyComplexData = { name: 'TelemetryPacket', version: 42, layer: { name: 'SensorReadings', size: 1024 } }; const pbfWriter = new Pbf(); writeData(myData, pbfWriter); const encodedBuffer: Uint8Array = pbfWriter.finish(); console.log('Encoded buffer (Uint8Array):', encodedBuffer); console.log('Encoded buffer length:', encodedBuffer.length, 'bytes'); const pbfReader = new Pbf(encodedBuffer); const decodedData: MyComplexData = pbfReader.readFields(readData, {} as MyComplexData); console.log('Decoded data:', decodedData);

Debug

Known issues

breakingPBF v4.0.0 completely dropped CommonJS support and is now exclusively distributed as an ES module. Direct `require()` statements will fail.

fix

Refactor your codebase to use ES module `import` and `export` syntax. If targeting environments that do not support ESM natively, use a transpiler like Babel or webpack.

affects: >=4.0.0

breakingThe underlying codebase was rewritten to use modern ES syntax in v4.0.0. While this improves maintainability and performance, it might break compatibility with very old JavaScript environments (e.g., Internet Explorer 11) that lack support for these features.

fix

Ensure your target runtime environment supports modern ES syntax or integrate a transpilation step (e.g., Babel) into your build process to downlevel the code.

affects: >=4.0.0

breakingPBF's CLI tool for generating JavaScript modules from `.proto` files now outputs ES modules by default since v4.0.0. Previously generated CommonJS modules are incompatible with this new default.

fix

Update your build scripts to handle ES module output (e.g., change `require` to `import` in generated files, or use bundlers). If CommonJS output is strictly required for generated code, use the `--legacy` flag when running the `pbf` CLI tool: `pbf --legacy example.proto > example.js`.

affects: >=4.0.0

breakingCode generation in v4.0.0 was overhauled to produce simpler, more compact code with flat exports of read and write functions, rather than nested objects (e.g., `read.Example` vs `readExample`).

fix

Adjust your import statements and code logic to use the new flat export structure for generated read and write functions. For example, change `read.MyMessage(pbf)` to `readMyMessage(pbf)`.

affects: >=4.0.0

gotchaThe `Pbf` constructor's `buf` argument was incorrectly typed as mandatory in versions prior to 4.0.1, despite being optional in practice. This could lead to TypeScript errors when instantiating `new Pbf()` without arguments.

fix

Update to PBF v4.0.1 or higher to get the corrected typings, which mark the `buf` parameter as optional.

affects: >=4.0.0 <4.0.1

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use `require()` to import PBF or code generated by PBF in an environment configured for ES modules, or in PBF v4+ which is ESM-only.

fix

Change `const Pbf = require('pbf');` to `import Pbf from 'pbf';`. For generated code, change `const { readMyMessage } = require('./my-schema');` to `import { readMyMessage } from './my-schema.js';`.

TypeError: pbf_1.default is not a constructor

This error often occurs when an ES module that uses a default export (like PBF v4) is incorrectly imported in a CommonJS context that doesn't properly handle `default` properties, or when a bundler/transpiler misinterprets the import.

fix

Ensure your project is configured for ES modules and use `import Pbf from 'pbf';`. If using TypeScript, check `tsconfig.json` for `"esModuleInterop": true` and `"module": "NodeNext"` or `"ES2020"`.

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

This typically indicates that generated read/write functions are being accessed incorrectly after the v4.0.0 code generation overhaul, which flattened exports from nested objects.

fix

Review your import statements for generated code. Instead of `import { read } from './my-schema.js'; read.MyMessage(pbf);`, use `import { readMyMessage } from './my-schema.js'; readMyMessage(pbf);`.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

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

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