Skip to content
Protobuf-ES

FAQ

Why not use string unions for Protobuf enums instead of TypeScript enum?

Section titled “Why not use string unions for Protobuf enums instead of TypeScript enum?”

String unions look attractive, but they lose important Protobuf behavior.

Enum numbers can be semantically meaningful. Some schemas use them as bit flags. Older generated code also needs to tolerate newer enum values it has never seen before.

TypeScript enums are not perfect, especially after TypeScript 5.0 tightened enum typing, but they still model Protobuf’s behavior better than string unions for the supported TypeScript range.

Why are enum values not generated in PascalCase?

Section titled “Why are enum values not generated in PascalCase?”

Generated enum value names follow the Protobuf source.

That keeps generated code aligned with the Protobuf JSON format, which uses the source enum names. It also matches the Buf style guide, which recommends UPPER_SNAKE_CASE enum values.

Why use bigint for 64-bit integers?

Section titled “Why use bigint for 64-bit integers?”

bigint is the best fit for 64-bit Protobuf integer types.

JavaScript numbers are only safe up to Number.MAX_SAFE_INTEGER, which is smaller than the full 64-bit range. bigint avoids silent precision loss. In environments without bigint, Protobuf-ES falls back to strings so values still round-trip safely.

How does Protobuf-ES compare to protoc’s JavaScript generator?

Section titled “How does Protobuf-ES compare to protoc’s JavaScript generator?”

The official google-protobuf generator emits getter and setter classes, uses CommonJS, and lags behind on Protobuf Edition support. Protobuf-ES generates plain object messages, ESM by default, with full Edition 2024 support. The public Protobuf conformance runner tracks failures for both implementations.

Why doesn’t Protobuf-ES expose more plugin options?

Section titled “Why doesn’t Protobuf-ES expose more plugin options?”

Protobuf-ES is intentionally opinionated.

Too many options make code generation harder to learn and debug, and harder for downstream tools to support consistently. New options are added when there is a real interoperability or compatibility need, not for stylistic preferences.

Parcel or Metro fails to resolve imports

Section titled “Parcel or Metro fails to resolve imports”

Protobuf-ES uses package exports.

If Parcel reports a failure to resolve @bufbuild/protobuf/codegenv2 (or codegenv1 for older generated code), enable package exports in Parcel.

If Metro or Expo reports the same kind of failure, enable package exports in Metro.

The plugin generates missing imports

Section titled “The plugin generates missing imports”

The Buf CLI does not generate dependencies by default.

If your schema imports something like buf/validate/validate.proto, generated code will import the corresponding generated module too. To generate those imported files, set include_imports: true in buf.gen.yaml:

version: v2
plugins:
  - local: protoc-gen-es
    out: src/gen
    include_imports: true

Is serialization deterministic?

Section titled “Is serialization deterministic?”

Binary and JSON serialization are deterministic within a version of Protobuf-ES.

Regular fields are ordered by field number. Map entries, repeated fields, and extensions are ordered by insertion.