{"id":15488,"library":"ts-proto","title":"ts-proto: TypeScript Protobuf Generator","description":"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.","status":"active","version":"2.11.6","language":"javascript","source_language":"en","source_url":"https://github.com/stephenh/ts-proto","tags":["javascript","typescript"],"install":[{"cmd":"npm install ts-proto","lang":"bash","label":"npm"},{"cmd":"yarn add ts-proto","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-proto","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for Protobuf serialization and deserialization in ts-proto v2.x and later.","package":"@bufbuild/protobuf","optional":false},{"reason":"Used 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.","package":"long","optional":true}],"imports":[{"note":"Generated code is ESM-first. `Person` refers to both the TypeScript interface and the runtime object with `encode`/`decode` methods.","wrong":"const { Person } = require('./person');","symbol":"Person","correct":"import { Person } from './person';"},{"note":"Service interfaces are named exports. The specific file path depends on your .proto file and `protoc` output.","wrong":"import PingService from './service';","symbol":"PingService","correct":"import { PingService } from './service';"},{"note":"Since ts-proto v2.x, low-level Protobuf serialization relies on `@bufbuild/protobuf/wire` instead of `protobufjs`.","wrong":"import { Writer, Reader } from 'protobufjs/minimal';","symbol":"BinaryReader, BinaryWriter","correct":"import { BinaryReader, BinaryWriter } from '@bufbuild/protobuf/wire';"}],"quickstart":{"code":"/* simple.proto */\nsyntax = \"proto3\";\n\npackage example;\n\nmessage Person {\n  string name = 1;\n  int32 id = 2;\n  string email = 3;\n}\n\nmessage PingRequest {\n  string message = 1;\n}\n\nmessage PingResponse {\n  string message = 1;\n}\n\nservice PingService {\n  rpc Ping(PingRequest) returns (PingResponse);\n}\n\n// Terminal commands\n// 1. Install ts-proto\nnpm install ts-proto\n\n// 2. Install protoc (if not already installed, see grpc.io/docs/protoc-installation)\n\n// 3. Generate TypeScript files\nprotoc \\\n  --plugin=./node_modules/.bin/protoc-gen-ts_proto \\\n  --ts_proto_out=. \\\n  ./simple.proto\n\n// Generated usage example (e.g., in index.ts)\n// import { Person, PingService } from './simple';\n//\n// const person: Person = { name: 'Alice', id: 123, email: 'alice@example.com' };\n// console.log('Person:', Person.toJSON(person));\n//\n// const pingRequest: PingRequest = { message: 'Hello, gRPC!' };\n// // In a real app, you would have a client implementation for PingService\n// // For example, a mock client:\n// class MockPingServiceClient implements PingService {\n//   ping(request: PingRequest): Promise<PingResponse> {\n//     console.log('Mock Ping request:', request.message);\n//     return Promise.resolve({ message: `Pong: ${request.message}` });\n//   }\n// }\n//\n// const client = new MockPingServiceClient();\n// client.ping(pingRequest).then(response => {\n//   console.log('Mock Ping response:', response.message);\n// });","lang":"typescript","description":"Demonstrates how to generate TypeScript types and interfaces from a `.proto` file using `protoc` and `ts-proto`, including basic message and service definitions."},"warnings":[{"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';`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use `protoc --plugin=protoc-gen-ts_proto=\".\\node_modules\\.bin\\protoc-gen-ts_proto.cmd\" --ts_proto_out=. ./simple.proto` on Windows.","message":"When running `protoc` on Windows, the plugin path requires a slightly different syntax due to how paths and arguments are handled.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Update your code to import `BinaryReader` and `BinaryWriter` from `@bufbuild/protobuf/wire` instead of `protobufjs`.","cause":"Attempting to use `protobufjs` Writer/Reader classes with `ts-proto` v2.x or later, which now uses `@bufbuild/protobuf` internally.","error":"TypeError: Writer is not a constructor"},{"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.","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.","error":"protoc-gen-ts_proto: program not found or is not executable"},{"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.","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`.","error":"TS2307: Cannot find module './my_proto_file' or its corresponding type declarations."}],"ecosystem":"npm"}