{"id":13485069,"url":"https://github.com/improbable-eng/ts-protoc-gen","last_synced_at":"2025-05-14T10:09:28.786Z","repository":{"id":37677477,"uuid":"84817943","full_name":"improbable-eng/ts-protoc-gen","owner":"improbable-eng","description":"Protocol Buffers Compiler (protoc) plugin for TypeScript and gRPC-Web.","archived":false,"fork":false,"pushed_at":"2024-02-01T02:49:32.000Z","size":1083,"stargazers_count":1386,"open_issues_count":47,"forks_count":170,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-10T07:04:40.037Z","etag":null,"topics":["grpc","grpc-web","plugin","protoc","protocol-buffers","ts","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/improbable-eng.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-03-13T11:18:31.000Z","updated_at":"2025-04-06T14:15:57.000Z","dependencies_parsed_at":"2024-04-17T18:08:34.656Z","dependency_job_id":null,"html_url":"https://github.com/improbable-eng/ts-protoc-gen","commit_stats":{"total_commits":184,"total_committers":34,"mean_commits":5.411764705882353,"dds":0.6141304347826086,"last_synced_commit":"2067c385c6a5e6ce32d8a16e87e87a593274b586"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/improbable-eng%2Fts-protoc-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/improbable-eng%2Fts-protoc-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/improbable-eng%2Fts-protoc-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/improbable-eng%2Fts-protoc-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/improbable-eng","download_url":"https://codeload.github.com/improbable-eng/ts-protoc-gen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248337981,"owners_count":21087140,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grpc","grpc-web","plugin","protoc","protocol-buffers","ts","typescript"],"created_at":"2024-07-31T17:01:44.931Z","updated_at":"2025-04-11T03:36:24.932Z","avatar_url":"https://github.com/improbable-eng.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","TypeScript (19)","Language-Specific","typescript"],"sub_categories":["TypeScript"],"readme":"[![Master Build](https://travis-ci.org/improbable-eng/ts-protoc-gen.svg?branch=master)](https://travis-ci.org/improbable-eng/ts-protoc-gen)\n[![NPM](https://img.shields.io/npm/v/ts-protoc-gen.svg)](https://www.npmjs.com/package/ts-protoc-gen)\n[![NPM](https://img.shields.io/npm/dm/ts-protoc-gen.svg)](https://www.npmjs.com/package/ts-protoc-gen)\n[![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n# ts-protoc-gen\n\n\u003e Protoc Plugin for generating TypeScript Declarations\n\nThis repository contains a [protoc](https://github.com/google/protobuf) plugin that generates TypeScript declarations\n(`.d.ts` files) that match the JavaScript output of `protoc --js_out=import_style=commonjs,binary`. This plugin can\nalso output service definitions as both `.js` and `.d.ts` files in the structure required by [grpc-web](https://github.com/improbable-eng/grpc-web), and as `.d.ts` files in the structure required by [grpc-node](https://github.com/grpc/grpc-node).\n\nThis plugin is tested and written using TypeScript 2.7.\n\n## Installation\n\n### npm\n\nAs a prerequisite, download or install `protoc` (the protocol buffer compiler) for your platform from the [github releases page](https://github.com/google/protobuf/releases) or via a package manager (ie: [brew](http://brewformulas.org/Protobuf), [apt](https://www.ubuntuupdates.org/pm/protobuf-compiler)).\n\nFor the latest stable version of the ts-protoc-gen plugin:\n\n```bash\nnpm install ts-protoc-gen\n```\n\nFor our latest build straight from master:\n\n```bash\nnpm install ts-protoc-gen@next\n```\n\n### bazel\n\nThe bazel rules have been moved to a separate project [here](https://github.com/Dig-Doug/rules_typescript_proto).\nThere is a\n[migration guide](https://github.com/Dig-Doug/rules_typescript_proto/blob/master/docs/migrating_from_ts_protoc_gen.md)\nfor existing users.\n\n## Contributing\n\nContributions are welcome! Please refer to [CONTRIBUTING.md](https://github.com/improbable-eng/ts-protoc-gen/blob/master/CONTRIBUTING.md) for more information.\n\n## Usage\n\nAs mentioned above, this plugin for `protoc` serves two purposes:\n\n1. Generating TypeScript Definitions for CommonJS modules generated by protoc\n2. Generating gRPC service clients for use with [grpc-web](https://github.com/improbable-eng/grpc-web) or [grpc-node](https://github.com/grpc/grpc-node).\n\n### Generating TypeScript Definitions for CommonJS modules generated by protoc\n\nBy default, protoc will generate ES5 code when the `--js_out` flag is used (see [javascript compiler documentation](https://github.com/google/protobuf/tree/master/js)). You have the choice of two module syntaxes, [CommonJS](https://nodejs.org/docs/latest-v8.x/api/modules.html) or [closure](https://developers.google.com/closure/library/docs/tutorial). This plugin (`ts-protoc-gen`) can be used to generate Typescript definition files (`.d.ts`) to provide type hints for CommonJS modules only.\n\nTo generate TypeScript definitions you must first configure `protoc` to use this plugin and then specify where you want the TypeScript definitions to be written to using the `--ts_out` flag.\n\n```bash\n# Path to this plugin\nPROTOC_GEN_TS_PATH=\"./node_modules/.bin/protoc-gen-ts\"\n\n# Directory to write generated code to (.js and .d.ts files)\nOUT_DIR=\"./generated\"\n\nprotoc \\\n    --plugin=\"protoc-gen-ts=${PROTOC_GEN_TS_PATH}\" \\\n    --js_out=\"import_style=commonjs,binary:${OUT_DIR}\" \\\n    --ts_out=\"${OUT_DIR}\" \\\n    users.proto base.proto\n```\n\nIn the above example, the `generated` folder will contain both `.js` and `.d.ts` files which you can reference in your TypeScript project to get full type completion and make use of ES6-style import statements, eg:\n\n```js\nimport { MyMessage } from \"../generated/users_pb\";\n\nconst msg = new MyMessage();\nmsg.setName(\"John Doe\");\n```\n\n### Generating gRPC Service Stubs for use with grpc-web\n\n[gRPC](https://grpc.io/) is a framework that enables client and server applications to communicate transparently, and makes it easier to build connected systems.\n\n[grpc-web](https://github.com/improbable-eng/grpc-web) is a comparability layer on both the server and client-side which allows gRPC to function natively in modern web-browsers.\n\nTo generate client-side service stubs from your protobuf files you must configure ts-protoc-gen to emit service definitions by passing the `service=grpc-web` param to the `--ts_out` flag, eg:\n\n```\n# Path to this plugin, Note this must be an abolsute path on Windows (see #15)\nPROTOC_GEN_TS_PATH=\"./node_modules/.bin/protoc-gen-ts\"\n\n# Directory to write generated code to (.js and .d.ts files)\nOUT_DIR=\"./generated\"\n\nprotoc \\\n    --plugin=\"protoc-gen-ts=${PROTOC_GEN_TS_PATH}\" \\\n    --js_out=\"import_style=commonjs,binary:${OUT_DIR}\" \\\n    --ts_out=\"service=grpc-web:${OUT_DIR}\" \\\n    users.proto base.proto\n```\n\nThe `generated` folder will now contain both `pb_service.js` and `pb_service.d.ts` files which you can reference in your TypeScript project to make RPCs.\n\n**Note** Note that these modules require a CommonJS environment. If you intend to consume these stubs in a browser environment you will need to use a module bundler such as [webpack](https://webpack.js.org/).\n**Note** Both `js` and `d.ts` service files will be generated regardless of whether there are service definitions in the proto files.\n\n```js\nimport {\n  UserServiceClient,\n  GetUserRequest\n} from \"../generated/users_pb_service\";\n\nconst client = new UserServiceClient(\"https://my.grpc/server\");\nconst req = new GetUserRequest();\nreq.setUsername(\"johndoe\");\nclient.getUser(req, (err, user) =\u003e {\n  /* ... */\n});\n```\n\n### Generating gRPC Service Stubs for use with grpc-node\n\nThis plugin can generate `.d.ts` files for gRPC service definitions as required by [grpc-node](https://github.com/grpc/grpc-node).\n\nTo generate these declaration files from your protobuf files you must configure ts-protoc-gen to emit service definitions by passing the `service=grpc-node` param to the `--ts_out` flag, eg:\n\n```\n# Path to this plugin, Note this must be an abolsute path on Windows (see #15)\nPROTOC_GEN_TS_PATH=\"./node_modules/.bin/protoc-gen-ts\"\n\n# Path to the grpc_node_plugin\nPROTOC_GEN_GRPC_PATH=\"./node_modules/.bin/grpc_tools_node_protoc_plugin\"\n\n# Directory to write generated code to (.js and .d.ts files)\nOUT_DIR=\"./generated\"\n\nprotoc \\\n    --plugin=\"protoc-gen-ts=${PROTOC_GEN_TS_PATH}\" \\\n    --plugin=protoc-gen-grpc=${PROTOC_GEN_GRPC_PATH} \\\n    --js_out=\"import_style=commonjs,binary:${OUT_DIR}\" \\\n    --ts_out=\"service=grpc-node:${OUT_DIR}\" \\\n    --grpc_out=\"${OUT_DIR}\" \\\n    users.proto base.proto\n```\n\nThe `generated` folder will now contain both `_grpc_pb.js` and `_grpc_pb.d.ts` files which you can reference in your TypeScript project to make RPCs.\n\n**Note** This plugin does not generate the `_grpc_pb.js` files itself; those are generated by the protoc-gen-grpc plugin. This plugin only generates the `_grpc_pb.d.ts` files.\n\n#### Using `@grpc/grpc-js` instead of `grpc`\n\nAdd a mode parameter to generate files that import `@grpc/grpc-js` instead of `grpc`, for example:\n\n```\n--ts_out=\"service=grpc-node,mode=grpc-js:${OUT_DIR}\"\n```\n\nYou'll also need to specify the `grpc_js` option within the `--grpc_out` flag, for example:\n\n```\n--grpc_out=\"grpc_js:${OUT_DIR}\"\n```\n\nIf you're consuming the server interface types you'll need to use version `@grpc/grpc-js@1.2.0` or higher.\n\n## Examples\n\n- [Example output](https://github.com/improbable-eng/ts-protoc-gen/tree/master/examples) -- Code generated by `ts-protoc-gen`.\n- [Packaging the output as a node module](https://github.com/improbable-eng/ts-protoc-gen/issues/173) -- Example of how to use the generated code as a dependendecy of another module.\n\n## Gotchas\n\nBy default the google-protobuf library will use the JavaScript number type to store 64bit float and integer values; this can lead to overflow problems as you exceed JavaScript's `Number.MAX_VALUE`. To work around this, you should consider using the `jstype` annotation on any 64bit fields, ie:\n\n```proto\nmessage Example {\n  uint64 bigInt = 1 [jstype = JS_STRING];\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimprobable-eng%2Fts-protoc-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimprobable-eng%2Fts-protoc-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimprobable-eng%2Fts-protoc-gen/lists"}