protodef-protobuf

1.0.0 verified Fri May 01 auth: no javascript

A transpiler and runtime for using Google Protocol Buffers (.proto files) with ProtoDef in Node.js. Version 1.0.0 is the current stable release; the package is actively maintained with an irregular release cadence (last two releases: 0.0.2 and 1.0.0). Key differentiators include support for Proto2 and Proto3, nested messages, enums, maps, packed repeated fields, extensions, imports (including Google well-known types), and a protobuf_message container for length-prefixing. It offers both a compiler mode for high performance via ProtoDef's AOT compiler and an interpreter mode for dynamic schemas. Compared to alternatives like protobuf.js or protobuf-es, this library integrates tightly with the ProtoDef ecosystem, making it suitable for projects already using ProtoDef for protocol definitions.

Common errors

error TypeError: pp.transpile is not a function ↓

cause Missing require('protodef-protobuf') or incorrect import.

fix

Ensure require or dynamic import is used: const pp = require('protodef-protobuf');

error Error: protobuf_message type not found ↓

cause Missing call to pp.addTypesToCompiler(compiler).

fix

Add pp.addTypesToCompiler(compiler) before compiler.addTypesToCompile(protocol).

error Error: Type 'chat_ChatMessage' not defined ↓

cause Mismatch between generated type name and use in protocol.

fix

Check generatedSchema keys for correct type name; use e.g. 'chat_ChatMessage'.

error Error: Cannot find module 'protobufjs' ↓

cause Missing protobufjs dependency (peer).

fix

Install protobufjs: npm install protobufjs

Warnings

breaking Version 1.0.0 is first stable release; API may have changed from 0.0.x versions. ↓

fix Review CHANGELOG for breaking changes; update imports and transpile() calls.

gotcha The 'transpile' function expects an array of schema strings, not a single string. ↓

fix Pass schema(s) as array: pp.transpile([schema])

gotcha Proto type names are mangled: package_PascalCaseMessage (e.g. 'chat_ChatMessage'). ↓

fix Use the naming convention as shown in generatedSchema keys.

deprecated Usage with 'protodef' interpreter mode may be deprecated; compiler mode is recommended. ↓

fix Prefer ProtoDefCompiler over ProtoDef for better performance.

Install

npm install protodef-protobuf

yarn add protodef-protobuf

pnpm add protodef-protobuf

Imports

default
wrong
```
import pp from 'protodef-protobuf'
```
correct
```
const pp = require('protodef-protobuf')
```
CommonJS package; no default ESM export. Use require() or dynamic import().

transpile

wrong

import { transpile } from 'protodef-protobuf'

correct

const { transpile } = require('protodef-protobuf')

Available as named export via destructuring from require().

addTypesToCompiler
```
const { addTypesToCompiler } = require('protodef-protobuf')
```
Used to register protobuf types with ProtoDefCompiler before compiling.

Quickstart

Transpile a .proto schema, compile with ProtoDef, and encode/decode a protobuf message using the library.

const { ProtoDefCompiler } = require('protodef').Compiler;
const pp = require('protodef-protobuf');

const schema = `
  syntax = "proto3";
  package chat;
  message ChatMessage {
    string user_id = 1;
    string content = 2;
  }
`;

const generatedSchema = pp.transpile([schema]);
const protocol = {
  ...generatedSchema,
  packet_hello: ['protobuf_message', {
    lengthType: 'varint',
    type: 'chat_ChatMessage'
  }]
};

const compiler = new ProtoDefCompiler();
pp.addTypesToCompiler(compiler);
compiler.addTypesToCompile(protocol);
const proto = compiler.compileProtoDefSync();

const data = { user_id: 'user123', content: 'Hello, world!' };
const encoded = proto.createPacketBuffer('packet_hello', data);
const decoded = proto.parsePacketBuffer('packet_hello', encoded);
console.log(decoded);