{"id":26112,"library":"protoc-gen-grpc","title":"protoc-gen-grpc-ts","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/stultuss/protoc-gen-grpc-ts","tags":["javascript","TypeScript","Protobuf","gRPC"],"install":[{"cmd":"npm install protoc-gen-grpc","lang":"bash","label":"npm"},{"cmd":"yarn add protoc-gen-grpc","lang":"bash","label":"yarn"},{"cmd":"pnpm add protoc-gen-grpc","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"protoc (Protocol Buffers compiler) must be installed separately to run the protoc command with this plugin.","package":"protoc","optional":true},{"reason":"Required at runtime for the generated JavaScript protobuf messages; this plugin generates types that depend on the google-protobuf types.","package":"google-protobuf","optional":false},{"reason":"One of the supported gRPC runtimes; if using @grpc/grpc-js, then grpc is optional.","package":"grpc","optional":true},{"reason":"One of the supported gRPC runtimes; if using grpc, then @grpc/grpc-js is optional.","package":"@grpc/grpc-js","optional":true}],"imports":[{"note":"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.","wrong":"const ProductServiceService = require('./path/to/generated/product_grpc_pb').ProductServiceService;","symbol":"ProductServiceService","correct":"import { ProductServiceService } from './path/to/generated/product_grpc_pb';"},{"note":"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.","wrong":"import product_pb from './path/to/generated/product_pb';","symbol":"product_pb","correct":"import * as product_pb from './path/to/generated/product_pb';"},{"note":"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'.","wrong":"import grpc from '@grpc/grpc-js';","symbol":"grpc","correct":"import * as grpc from '@grpc/grpc-js';"}],"quickstart":{"code":"// Install protoc-gen-grpc globally\nnpm install -g protoc-gen-grpc\n\n# Generate JavaScript and TypeScript definitions for a .proto file\n# Make sure protoc is installed (https://github.com/protocolbuffers/protobuf/releases)\n\nprotoc \\\n  --js_out=import_style=commonjs,binary:./generated \\\n  --grpc_out=grpc_js:./generated \\\n  --ts_out=grpc_js:./generated \\\n  --proto_path=./protos \\\n  ./protos/example.proto\n\n# Now you can use the generated types in your TypeScript server\nimport * as grpc from '@grpc/grpc-js';\nimport { ExampleServiceService } from './generated/example_grpc_pb';\n\nconst server = new grpc.Server();\nserver.addService(ExampleServiceService, { /* your implementation */ });\n","lang":"typescript","description":"Shows global installation, protoc invocation (with three output plugins), and then TypeScript server snippet using the generated service definition."},"warnings":[{"fix":"Install 'protoc-gen-grpc-ts' for TypeScript types, not 'protoc-gen-grpc' (which is for JavaScript).","message":"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'.","severity":"deprecated","affected_versions":">=0.0.0"},{"fix":"Run: npm_config_target_arch=x64 npm i grpc-tools","message":"On Apple M1 (arm64), install grpc-tools with architecture flag: npm_config_target_arch=x64 npm i grpc-tools","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Run: npm install request -g","message":"Node-pre-gyp may fail to download binary due to missing request module; install request globally as workaround.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"npm config set unsafe-perm true && npm install -g protoc-gen-grpc-ts","message":"NPM unsafe-perm may need to be set to true for global installs: npm config set unsafe-perm true or use --unsafe-perm flag.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use named imports like 'import { ServiceName } from ...' instead of 'import ServiceName from ...'.","message":"Version 2.x switched from default export to named exports; old import patterns break.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"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","cause":"protoc cannot find the protoc-gen-ts plugin; not installed or not in PATH.","error":"Error: Plugin \"protoc-gen-ts\" not found or is not executable."},{"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'.","cause":"The plugin is not properly registered; protoc does not recognize --ts_out.","error":"error: unknown flag: --ts_out"},{"fix":"Check the output directory and adjust the import path in your TypeScript files. Use relative or absolute path as needed.","cause":"Generated JavaScript/TypeScript files are not in the expected location or import path is wrong.","error":"Module not found: Can't resolve './path/to/generated/product_pb'"},{"fix":"Verify the .proto file defines the service correctly and that the generated file exports it with the exact name (e.g., ProductServiceService).","cause":"Attempting to import a service that does not exist; possibly wrong generated file or misnamed service.","error":"TypeError: Cannot read properties of undefined (reading 'ProductServiceService')"},{"fix":"Use npm config set prefix to a directory you own, or use sudo (not recommended), or install locally with npx.","cause":"Permission denied when trying to install globally without appropriate permissions.","error":"npm ERR! code EACCES npm ERR! syscall mkdir ..."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}