protobuf.js

If you use protoc, you can use protoc-gen-pbjs as an aggregate generator. Each invocation writes one JavaScript module and (if dts is specified) one matching declaration file.

By default, it emits index.js with target=static-module and wrap=esm. You can customize this using --pbjs_opt.

Customization via --pbjs_opt:

• file=PATH: Choose the aggregate output file.
• target=json-module: Use JSON module.
• wrap=commonjs: Use CommonJS output.
• keep-case: Preserve descriptor field names.

protoc \
  --plugin=protoc-gen-pbjs=./node_modules/.bin/protoc-gen-pbjs \
  --pbjs_out=gen \
  --pbjs_opt=dts \
  proto/awesome.proto

You can load a .proto file at runtime using protobuf.load(). This returns a Root object which you can use to look up specific message types.

Note: By default, protobuf.js converts .proto field names to camelCase. To preserve the exact field names from your .proto file, use the keepCase option when loading.

const protobuf = require("protobufjs");

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

To override default options when running the command, use the -q or --query flag followed by a key-value pair in the format key=value.

-q module=protobufjs

Use fromObject and toObject to handle the boundary between Protobuf message instances and standard JavaScript objects. This is useful for handling types like Enums, 64-bit integers, and Base64 bytes.

• fromObject(object): Converts a broad JavaScript object into a formal message instance.
• toObject(message, options): Converts a message instance into a plain object using specific ConversionOptions.

const message = AwesomeMessage.fromObject({ awesomeField: 42 });
const object = AwesomeMessage.toObject(message, {
  longs: String,
  enums: String,
  bytes: String
});

To convert data to binary and back, use the encode and decode methods on the message type.

• encode(message): Expects a message instance or a plain object. It returns a Writer which must be finalized with .finish() to get the buffer.
• decode(buffer): Decodes binary data into a message instance.
• create(payload): Useful for creating a message instance from a plain object before encoding.
• verify(object): Validates if a plain object matches the schema. Returns null if valid, or an error string if invalid.

const payload = { awesomeField: "hello" };

// Optionally create a message instance from already valid data
const message = AwesomeMessage.create(payload);

const encoded = AwesomeMessage.encode(message).finish();
const decoded = AwesomeMessage.decode(encoded);

To use protobuf.js in your project, install the main package via npm:

npm install protobufjs

If you need the command line utility for generating reflection bundles, static code, or TypeScript declarations, install the protobufjs-cli add-on as a dev dependency:

npm install --save-dev protobufjs-cli

Reflection bundles store schemas as JSON metadata, avoiding the need to parse .proto files at runtime. This allows browsers to load schema metadata in a single request.

• JSON bundle (-t json): Requires protobufjs/light.js. Best for loading schemas via protobuf.Root.fromJSON(bundle).
• JSON module (-t json-module): Requires protobufjs/light.js. Exports the reflection root and, with -w esm, provides top-level named exports. Note: Message instances should be created using MyMessage.create(...) rather than constructors.

Install the protobufjs-cli package as a development dependency to access the pbjs and pbts command-line utilities for code generation.

npm install --save-dev protobufjs-cli

Use protobufjs-cli to generate static, reflection-free JavaScript code. Static modules are optimized for performance and work in CSP-restricted environments because they do not require unsafe-eval. They only require protobufjs/minimal.js at runtime. You can specify the module format using the -w (or --wrap) flag (e.g., esm, commonjs, amd, closure).

npx pbjs -t static-module -w esm -o awesome.js --dts awesome.proto

protobuf.js provides built-in TypeScript support. The runtime API is typed, and you can generate matching .d.ts declarations during code generation using the --dts flag.

For oneof fields, the generated declarations provide type narrowing. You can also use the $[TypeName].$Shape type for plain-object inputs to ensure they match the expected schema shape.

// Example of type-safe oneof usage
const profile = Profile.create({
  contact: "email",
  email: "hello@example.com"
});

if (profile.contact === "email") {
  profile.email; // string
}

// Using the $Shape type for plain objects
const object: Profile.$Shape = {
  contact: "email",
  email: "hello@example.com"
};