protobufjs 8.x

Complete instructions

Verified against protobufjs@8.8.0 on 2026-09-08. 2 of 2 examples executed.

protobufjs ^8.0.0

What this package provides

protobufjs is the full runtime package: static code, reflection, and .proto parsing. Its documented variants are:

• protobufjs: static code, reflection, and .proto parsing
• protobufjs/light: static code and reflection
• protobufjs/minimal: static code only

The package exposes reflection constructors and types including Root, Type, Field, Message, Enum, Service, Method, OneOf, and Namespace. It also exposes Reader, Writer, and the converter, rpc, types, and util namespaces.

Common runtime workflow

The usual reflection workflow is:

const root = await protobuf.load("awesome.proto");
const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");

load() accepts either a promise-based or callback-based use. loadSync() is documented for synchronous Node.js loading. A .proto field name is converted to camelCase by default; use keepCase when the original spelling must be retained.

In a standalone script, loading a file is not demonstrated here because examples are run without a filesystem. The programmatic reflection API is useful when the schema can be built in memory.

Build a schema with reflection

Create a Type, add Field objects, put the type in a Root, and look it up by its fully qualified name:

import assert from "node:assert/strict";
import protobuf from "protobufjs";

const AwesomeMessage = new protobuf.Type("AwesomeMessage")
  .add(new protobuf.Field("awesomeField", 1, "string"));

const root = new protobuf.Root()
  .define("awesomepackage")
  .add(AwesomeMessage);

const MessageType = root.lookupType("awesomepackage.AwesomeMessage");
assert.equal(MessageType, AwesomeMessage);

const message = MessageType.create({ awesomeField: "hello" });
assert.equal(message.awesomeField, "hello");

Message lifecycle and binary encoding

The documented message operations are:

• create(properties) creates a message instance.
• verify(object) returns null for a valid object or an error string.
• fromObject(object) converts a plain object to a message.
• toObject(message, options?) converts a message to a plain object.
• encode(message) and encodeDelimited(message) return a Writer.
• Call .finish() on the writer to obtain encoded bytes.
• decode(bytesOrReader) and decodeDelimited(bytesOrReader) decode messages.

Use create() for the ordinary runtime path. Do not assume a generated message type should be called with new; the documented reflection usage is MessageType.create(...).

import assert from "node:assert/strict";
import protobuf from "protobufjs";

const MessageType = new protobuf.Type("Greeting")
  .add(new protobuf.Field("text", 1, "string"));

const message = MessageType.create({ text: "hello" });
assert.equal(MessageType.verify(message), null);

const encoded = MessageType.encode(message).finish();
const decoded = MessageType.decode(encoded);
assert.equal(decoded.text, "hello");

const plain = MessageType.toObject(decoded);
assert.equal(plain.text, "hello");

const converted = MessageType.fromObject({ text: "again" });
assert.equal(converted.text, "again");

const delimited = MessageType.encodeDelimited(message).finish();
const decodedDelimited = MessageType.decodeDelimited(delimited);
assert.equal(decodedDelimited.text, "hello");

Generated code and the CLI

The runtime package alone does not provide the pbjs code-generation command. Generation requires protobufjs-cli (or protoc-gen-pbjs), for example:

npm install --save-dev protobufjs-cli
npx pbjs -t static-module -w commonjs -o compiled.js --dts file1.proto file2.proto
npx pbjs -t json-module -w commonjs -o bundle.js --dts file1.proto file2.proto

static-module output is reflection-free and uses protobufjs/minimal.js. json-module output is reflection-backed and uses protobufjs/light.js. Generated modules are then consumed as ordinary imports.

The CLI documentation describes static-module output as non-functional on its own. Do not expect installing only protobufjs to provide the CLI or code generation.

Services

The documented service-client entry point is MyService.create(rpcImpl, requestDelimited?, responseDelimited?). The RPC implementation receives (method, requestData, callback) and must eventually invoke the callback with either an error or response bytes:

function myRpcImpl(method, requestData, callback) {
  performRequest(requestData, function (err, responseData) {
    callback(err, responseData);
  });
}

The service client requires a service definition and an RPC transport implementation; this skill does not provide a standalone service example because the supplied research does not document enough of the service-definition construction API to make one safely runnable without inventing details.

Version-specific caution

The ^8.0.0 range permits current 8.x releases; the researched npm page lists 8.8.0. The documented v8.0.0 breaking change is Edition 2024 support. Edition 2023 was added in v7.5.0. Be cautious when copying older examples: ordinary reflection loading and Type.create(...) remain the documented shape, but edition support is part of the v8 runtime.

Not covered

This skill does not cover the exact .proto schema syntax, descriptor conversion, ProtoJSON, Text Format, every reflection constructor, generated-module APIs in detail, CLI options beyond the shown commands, protoc-gen-pbjs, or the complete service-definition and transport setup. Those areas require documentation or tooling details not present in the supplied research.