protoc-gen-grpc-ts

3.0.0 verified Fri May 01 auth: no javascript

Protocol Buffers compiler (protoc) plugin to generate TypeScript type definitions (d.ts) for gRPC service interfaces and message types from .proto files. Version 3.0.0 supports both the 'grpc' and '@grpc/grpc-js' runtime packages. This plugin is not a code generator for JavaScript (you still need protoc-gen-grpc for JS), it only produces type declaration files for TypeScript projects. Can be installed globally or per project. Note: the plugin is designed for Node.js (engine >=16) and requires protoc installed separately.

Common errors

error Error: Plugin "protoc-gen-ts" not found or is not executable. ↓

cause protoc cannot find the protoc-gen-ts plugin; not installed or not in PATH.

fix

Ensure protoc-gen-grpc-ts is installed globally (npm install -g protoc-gen-grpc-ts) and that protoc can find it. Alternatively, specify full path: --plugin=protoc-gen-ts=/path/to/protoc-gen-ts

error error: unknown flag: --ts_out ↓

cause The plugin is not properly registered; protoc does not recognize --ts_out.

fix

Make sure the plugin executable is named exactly 'protoc-gen-ts' and is in PATH. Set unsafe-perm if needed. Verify with 'which protoc-gen-ts'.

error Module not found: Can't resolve './path/to/generated/product_pb' ↓

cause Generated JavaScript/TypeScript files are not in the expected location or import path is wrong.

fix

Check the output directory and adjust the import path in your TypeScript files. Use relative or absolute path as needed.

error TypeError: Cannot read properties of undefined (reading 'ProductServiceService') ↓

cause Attempting to import a service that does not exist; possibly wrong generated file or misnamed service.

fix

Verify the .proto file defines the service correctly and that the generated file exports it with the exact name (e.g., ProductServiceService).

error npm ERR! code EACCES npm ERR! syscall mkdir ... ↓

cause Permission denied when trying to install globally without appropriate permissions.

fix

Use npm config set prefix to a directory you own, or use sudo (not recommended), or install locally with npx.

Warnings

deprecated NPM package name 'protoc-gen-grpc' is the same as the JavaScript plugin; do not confuse with the TypeScript-only plugin 'protoc-gen-grpc-ts'. ↓

fix Install 'protoc-gen-grpc-ts' for TypeScript types, not 'protoc-gen-grpc' (which is for JavaScript).

gotcha On Apple M1 (arm64), install grpc-tools with architecture flag: npm_config_target_arch=x64 npm i grpc-tools ↓

fix Run: npm_config_target_arch=x64 npm i grpc-tools

gotcha Node-pre-gyp may fail to download binary due to missing request module; install request globally as workaround. ↓

fix Run: npm install request -g

gotcha NPM unsafe-perm may need to be set to true for global installs: npm config set unsafe-perm true or use --unsafe-perm flag. ↓

fix npm config set unsafe-perm true && npm install -g protoc-gen-grpc-ts

breaking Version 2.x switched from default export to named exports; old import patterns break. ↓

fix Use named imports like 'import { ServiceName } from ...' instead of 'import ServiceName from ...'.

Install

npm install protoc-gen-grpc

yarn add protoc-gen-grpc

pnpm add protoc-gen-grpc

Imports

ProductServiceService
wrong
```
const ProductServiceService = require('./path/to/generated/product_grpc_pb').ProductServiceService;
```
correct
```
import { ProductServiceService } from './path/to/generated/product_grpc_pb';
```
Generated TypeScript files export named constants (e.g., ProductServiceService) which are gRPC service definitions. Use ES module import for consistency. CommonJS require works but TypeScript may complain without esModuleInterop.
product_pb
wrong
```
import product_pb from './path/to/generated/product_pb';
```
correct
```
import * as product_pb from './path/to/generated/product_pb';
```
Generated protobuf message types are exported as a namespace; use 'import * as' to import all types. Default import will not work because there is no default export.
grpc
wrong
```
import grpc from '@grpc/grpc-js';
```
correct
```
import * as grpc from '@grpc/grpc-js';
```
The @grpc/grpc-js package uses a namespace export; you must use 'import * as' to get the grpc object. Without this, TypeScript will throw 'Module has no default export'.

Quickstart

Shows global installation, protoc invocation (with three output plugins), and then TypeScript server snippet using the generated service definition.

// Install protoc-gen-grpc globally
npm install -g protoc-gen-grpc

# Generate JavaScript and TypeScript definitions for a .proto file
# Make sure protoc is installed (https://github.com/protocolbuffers/protobuf/releases)

protoc \
  --js_out=import_style=commonjs,binary:./generated \
  --grpc_out=grpc_js:./generated \
  --ts_out=grpc_js:./generated \
  --proto_path=./protos \
  ./protos/example.proto

# Now you can use the generated types in your TypeScript server
import * as grpc from '@grpc/grpc-js';
import { ExampleServiceService } from './generated/example_grpc_pb';

const server = new grpc.Server();
server.addService(ExampleServiceService, { /* your implementation */ });