PBF: Low-Level Protocol Buffers for JavaScript

Common errors

• ReferenceError: require is not defined

  cause 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

  cause 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')

  cause 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);`.

Warnings

• breaking PBF 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.
• breaking The 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.
• breaking PBF'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`.
• breaking Code 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)`.
• gotcha The `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.

Install

• npm install pbf npm
• yarn add pbf yarn
• pnpm add pbf pnpm

Imports

• Pbf
  wrong:

  const Pbf = require('pbf');

  correct:

  import Pbf from '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)
  wrong:

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

  correct:

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

  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
  wrong:

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

  correct:

  import { compile } from '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.

Quickstart

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