ts-proto: TypeScript Protobuf Generator

Common errors

• TypeError: Writer is not a constructor

  cause 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

  cause 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.

  cause 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.

Warnings

• breaking ts-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';`.
• gotcha When 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.
• gotcha Generated 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.
• gotcha Ensure 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.

Install

• npm install ts-proto npm
• yarn add ts-proto yarn
• pnpm add ts-proto pnpm

Imports

• Person
  wrong:

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

  correct:

  import { Person } from './person';

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

  import PingService from './service';

  correct:

  import { PingService } from './service';

  Service interfaces are named exports. The specific file path depends on your .proto file and `protoc` output.
• BinaryReader, BinaryWriter
  wrong:

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

  correct:

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

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

Quickstart

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);
// });