Registry / serialization / protoc-gen-ts

protoc-gen-ts

library0.8.7jsnpmunverified

protoc-gen-ts is a `protoc` plugin that generates plain TypeScript source files from Protocol Buffer `.proto` definitions, effectively replacing separate `.d.ts` declaration files. It is actively maintained, with the current stable version being `0.8.7`, and new features/fixes are delivered through frequent minor releases. A key differentiator is its direct TypeScript output which eliminates common prefixes (e.g., `getField`) and exposes fields as standard getters/setters, along with `fromObject` and `toObject` methods for robust bidirectional mapping between JSON and message instances, supporting deep structures without runtime type reflection. It offers native support for gRPC Node (`@grpc/grpc-js`) and gRPC Web, including options for promise-based RPC calls. Messages defined within a `package` directive in the `.proto` file are by default encapsulated within a TypeScript namespace, though this behavior can be toggled.

serialization type-stubs

npm install protoc-gen-ts

github ↗package ↗

INSTALL

IMPORT

SIG · PROTOC-GEN-TS

protoc-gen-ts

serializationjavascriptv0.8.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Change

✓ import { Change } from './myproto_pb';

✗ const { Change } = require('./myproto_pb');

Messages are generated as ES Modules. The path depends on your `--ts_out` setting and `package` name in your .proto file (e.g., `myproto_pb` if `package mypackage` is used, or `myproto` if no package).

Kind

✓ import { Kind } from './myproto_pb';

✗ import Kind from './myproto_pb';

Enums are generated as named exports. The import path and filename reflect the proto file and package structure.

MyService

✓ import { MyServiceClient } from './myproto_pb';

✗ import { MyService } from './myproto_pb';

gRPC services generate a client class (e.g., `MyServiceClient`) and potentially an interface (e.g., `IMyService`). The exact name depends on the proto service definition.

This quickstart demonstrates how to create, serialize, and deserialize a Protocol Buffer message using the generated TypeScript classes. It also illustrates the convenient `fromObject` and `toObject` methods for JSON interoperability.

import { Change, Kind, Author } from './myproto_pb'; // Assumes protoc-gen-ts generated './myproto_pb.ts' // Construct a message instance const author = new Author({ name: 'mary poppins', role: 'maintainer' }); const change = new Change({ kind: Kind.UPDATED, patch: '@@ -7,11 +7,15 @@', tags: ['no prefix', 'as is'], name: 'patch for typescript 4.5', author: author }); // Serialize to bytes (Uint8Array) const bytes: Uint8Array = change.serialize(); console.log('Serialized bytes:', bytes); // Deserialize from bytes back into a message instance const receivedChange: Change = Change.deserialize(bytes); console.log('Deserialized Change object:', receivedChange); console.log('Kind:', receivedChange.kind === Kind.UPDATED); // true console.log('Author name:', receivedChange.author?.name); // mary poppins // Using fromObject for easier JSON-to-message mapping const jsonChange = Change.fromObject({ kind: Kind.DELETED, patch: 'deleted line', tags: ['cleanup'], id: '12345', author: { name: 'john doe', role: 'contributor' } }); console.log('Change from JSON:', jsonChange.toObject()); console.log('Author from JSON is an Author instance:', jsonChange.author instanceof Author);

protoc-gen-ts --version

Debug

Known issues

breakingIn version `0.8.5`, `getters` and `toObject` methods were changed to return the *default value* for a field if it is not present, instead of `undefined`. This affects behavior for optional fields, proto2 fields, and oneof fields that are not set, potentially requiring code adjustments if `undefined` or `null` checks were previously used.

fix

Review code that checks for the presence of fields or relies on `undefined` for unset fields. Explicitly check for field presence if distinguishing between an unset field and a field with its default value is critical. For oneof fields, check the `oneof_name` property to determine which field is set.

affects: >=0.8.5

deprecatedThe `index.bzl` file has been deprecated in version `0.8.7`. Users integrating with Bazel build systems may need to update their Bazel configurations to align with the new recommended practices for Bazel integration.

fix

Consult the official `protoc-gen-ts` documentation or GitHub repository for updated Bazel integration guidelines and migration paths.

affects: >=0.8.7

gotchaBy default, `protoc-gen-ts` generates TypeScript namespaces corresponding to the `package` directive in your `.proto` files. If you prefer a flatter module structure or encounter issues with namespace resolution, this behavior can be altered.

fix

Use the `--ts_opt=no_namespace` option when running `protoc` to disable namespace generation and have all generated types in the global module scope (or their respective file modules).

affects: >=0.8.0

gotcha`protoc-gen-ts` is a `protoc` plugin and must be discoverable by the `protoc` executable. If `protoc` cannot find the plugin, it will fail with an error indicating the program is not found.

fix

Ensure `protoc-gen-ts` is installed globally (`npm install -g protoc-gen-ts`) and that its installation directory is in your system's PATH. Alternatively, you can explicitly provide the plugin path to `protoc` using `--plugin=protoc-gen-ts=/path/to/protoc-gen-ts`.

affects: >=0.8.0

gotchaThe package `protoc-gen-ts` itself does not have runtime npm dependencies beyond standard Node.js/TypeScript. However, the *generated code* often relies on runtime libraries for gRPC functionality (e.g., `@grpc/grpc-js` or `grpc`). These must be installed separately in your project if you generate gRPC service clients/servers.

fix

If using gRPC functionality from generated code, ensure you have installed the appropriate gRPC runtime library: `npm install @grpc/grpc-js` for Node.js or include the necessary gRPC Web client libraries for browser environments.

affects: >=0.8.0

Errors

Common errors & fixes

protoc-gen-ts: program not found

The `protoc` compiler cannot locate the `protoc-gen-ts` executable in the system's PATH.

fix

Install `protoc-gen-ts` globally (`npm install -g protoc-gen-ts`) and ensure your PATH includes npm's global bin directory. Alternatively, specify the full path to the plugin: `protoc --plugin=protoc-gen-ts=$(which protoc-gen-ts) -I=...`.

TS2307: Cannot find module './myproto_pb' or its corresponding type declarations.

The TypeScript compiler cannot resolve the import path to the generated Protocol Buffer files, either due to incorrect path, missing `tsconfig.json` configuration, or the generated files not being in the include path.

fix

Verify that the `--ts_out` option in your `protoc` command points to the correct output directory. Ensure your `tsconfig.json` includes this directory in `include` or `files`, and that `baseUrl` and `paths` are configured correctly if you are using path aliases. Adjust import statements to match the actual generated file names and paths.

TypeError: Cannot read properties of undefined (reading 'name') at Object.fromObject

This typically occurs when `fromObject` is called with an invalid or unexpected JSON structure, such as a missing nested object or an array where a single object is expected, and an attempt is made to access properties on `undefined`.

fix

Ensure the JSON object passed to `fromObject` strictly adheres to the structure of your `.proto` message definition, especially for nested messages and repeated fields. Verify all required fields are present and correctly typed.

TS2339: Property 'myField' does not exist on type 'MyMessage'.

This can happen if you are trying to access a field using a name that does not match the generated TypeScript property, or if the field is part of a `oneof` and is not currently set, or if an older version of TypeScript is used that doesn't fully support certain generated constructs.

fix

Check your `.proto` file for the exact field name. By default, fields are named as-is. If `json_names` option is enabled, check for camelCase. For `oneof` fields, access the field through the `oneof_name` property first. Ensure your TypeScript version is compatible (e.g., `ts-5` is allowed as a peer dep since `0.8.7`).

Upgrade

Version history

0.8.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/thesayyn/protoc-gen-ts ↗

packagehttps://www.npmjs.com/package/protoc-gen-ts ↗