ts-proto

library2.11.6jsnpmunverified

ts-proto is a TypeScript code generation tool that transforms Protocol Buffer (`.proto`) schemas into strongly-typed, idiomatic TypeScript files. It provides robust type definitions for messages and services, along with utilities for encoding, decoding, and JSON serialization. Currently at version 2.11.6, the project maintains an active release cadence, with frequent bug fixes and feature enhancements, as seen in the recent 2.11.x releases addressing issues like `globalThis.Buffer` casting, `isolatedDeclarations` compatibility, and `NullValue` handling. A significant differentiator for ts-proto v2.x is its migration from the `protobufjs` library to `@bufbuild/protobuf` for low-level serialization, aiming for improved performance and maintainability. It also supports generating client implementations for various RPC frameworks including Twirp, gRPC-web, gRPC-js, and NestJS, offering a comprehensive solution for integrating Protobuf with TypeScript applications.

serialization devops

npm install ts-proto

github ↗package ↗

INSTALL

IMPORT

SIG · TS-PROTO

ts-proto

serializationjavascriptv2.11.6

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.

Person

✓ import { Person } from './person';

✗ const { Person } = require('./person');

Generated code is ESM-first. `Person` refers to both the TypeScript interface and the runtime object with `encode`/`decode` methods.

PingService

✓ import { PingService } from './service';

✗ import PingService from './service';

Service interfaces are named exports. The specific file path depends on your .proto file and `protoc` output.

BinaryReader, BinaryWriter

✓ import { BinaryReader, BinaryWriter } from '@bufbuild/protobuf/wire';

✗ import { Writer, Reader } from 'protobufjs/minimal';

Since ts-proto v2.x, low-level Protobuf serialization relies on `@bufbuild/protobuf/wire` instead of `protobufjs`.

Demonstrates how to generate TypeScript types and interfaces from a `.proto` file using `protoc` and `ts-proto`, including basic message and service definitions.

/* simple.proto */ syntax = "proto3"; package example; message Person { string name = 1; int32 id = 2; string email = 3; } message PingRequest { string message = 1; } message PingResponse { string message = 1; } service PingService { rpc Ping(PingRequest) returns (PingResponse); } // Terminal commands // 1. Install ts-proto npm install ts-proto // 2. Install protoc (if not already installed, see grpc.io/docs/protoc-installation) // 3. Generate TypeScript files protoc \ --plugin=./node_modules/.bin/protoc-gen-ts_proto \ --ts_proto_out=. \ ./simple.proto // Generated usage example (e.g., in index.ts) // import { Person, PingService } from './simple'; // // const person: Person = { name: 'Alice', id: 123, email: 'alice@example.com' }; // console.log('Person:', Person.toJSON(person)); // // const pingRequest: PingRequest = { message: 'Hello, gRPC!' }; // // In a real app, you would have a client implementation for PingService // // For example, a mock client: // class MockPingServiceClient implements PingService { // ping(request: PingRequest): Promise<PingResponse> { // console.log('Mock Ping request:', request.message); // return Promise.resolve({ message: `Pong: ${request.message}` }); // } // } // // const client = new MockPingServiceClient(); // client.ping(pingRequest).then(response => { // console.log('Mock Ping response:', response.message); // });

ts-proto --version

Debug

Known issues

breakingts-proto v2.x migrated its underlying Protobuf serialization library from `protobufjs` to `@bufbuild/protobuf`. Code directly using `protobufjs`'s `Writer` or `Reader` classes will break and needs to be updated.

fix

Update imports and usage of low-level serialization utilities from `protobufjs` to `@bufbuild/protobuf/wire`. For example, `import { BinaryReader, BinaryWriter } from '@bufbuild/protobuf/wire';`.

affects: >=2.0.0

gotchaWhen running `protoc` on Windows, the plugin path requires a slightly different syntax due to how paths and arguments are handled.

fix

Use `protoc --plugin=protoc-gen-ts_proto=".\node_modules\.bin\protoc-gen-ts_proto.cmd" --ts_proto_out=. ./simple.proto` on Windows.

affects: >=1.0.0

gotchaGenerated code is ESM-first. If your project uses CommonJS, you might need to configure your build tools or Node.js environment appropriately. Older `protobufjs` patterns of `require()` might not work directly.

fix

For projects requiring CommonJS compatibility, ensure your `tsconfig.json` has `"module": "CommonJS"` and potentially set `"esModuleInterop": true`. Alternatively, embrace ESM throughout your project by setting `"type": "module"` in `package.json` and using `import` statements.

affects: >=2.0.0

gotchaEnsure you are using a modern `protoc` compiler. Older versions (e.g., `protoc 3.0.0`) may not support the `--ts_proto_opt` flag or other features required by `ts-proto`.

fix

Refer to the official gRPC documentation for up-to-date `protoc` installation instructions for your platform and ensure you have a recent version installed.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Writer is not a constructor

Attempting to use `protobufjs` Writer/Reader classes with `ts-proto` v2.x or later, which now uses `@bufbuild/protobuf` internally.

fix

Update your code to import `BinaryReader` and `BinaryWriter` from `@bufbuild/protobuf/wire` instead of `protobufjs`.

protoc-gen-ts_proto: program not found or is not executable

The `protoc` compiler cannot find or execute the `ts-proto` plugin. This is often due to an incorrect path or permissions, especially on Windows.

fix

Verify the path to `protoc-gen-ts_proto` in your `node_modules/.bin` directory. On Windows, use the `.cmd` extension and the specific quoting/path format: `protoc --plugin=protoc-gen-ts_proto=".\node_modules\.bin\protoc-gen-ts_proto.cmd" --ts_proto_out=. ./simple.proto`. Ensure the file is executable.

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

TypeScript cannot resolve the generated `.ts` files, often because the `protoc` command hasn't been run, or the output directory is not included in `tsconfig.json`'s `include` or `paths`.

fix

First, run the `protoc` command to generate the TypeScript files. Then, ensure your `tsconfig.json` includes the output directory (e.g., `"include": ["src", "./"]`) and that `"moduleResolution": "node"` or `"node16"` is set.

Upgrade

Version history

2.11.6latest on npm

Audit

Dependencies

@bufbuild/protobufrequiredCore library for Protobuf serialization and deserialization in ts-proto v2.x and later.

longoptionalUsed internally by the generated code for handling 64-bit integer types when `forceLong=number` is enabled. Not always a direct dependency to declare but used at runtime.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/stephenh/ts-proto ↗

packagehttps://www.npmjs.com/package/ts-proto ↗