ts-protoc-gen - GitLite

KO | EN

gitlite — search

#hacktoberfest #typescript #llm #golang #android #machine-learning #deep-learning #linux #java #awesome #vue #pytorch #mcp #openai

ts-protoc-gen

(★ 1,395)

Protocol Buffers Compiler (protoc) plugin for TypeScript and gRPC-Web.

파일 탐색기

최종 버전 다운로드 (.zip)

- stale.yml
- protoc-gen-ts
- protoc-gen-ts.cmd
- - annotations.proto
  - casing.proto
  - empty_message_no_service.proto
  - enum_message.proto
  - extensions.proto
  - getter_name.proto
  - map_message.proto
  - oneof_message.proto
  - parent_message_v2.proto
  - parent_message_v3.proto
  - primitive_message_v2.proto
  - primitive_message_v3.proto
  - repeated_primitive_message.proto
  - reserved_words.proto
  - simple.proto
  - simple_service.proto
  - simplevalue.proto
  - well_known_message.proto
- - external_child_message.proto
  - external_enum.proto
- orphan.proto
- - common.ts
  - grpcnode.ts
  - grpcweb.ts
- - enum.ts
  - extensions.ts
  - FieldTypes.ts
  - fileDescriptorTSD.ts
  - message.ts
  - oneof.ts
- CodePrinter.ts
- ExportMap.ts
- index.ts
- parameters.ts
- Printer.ts
- util.ts
- WellKnown.ts
- - fakeGrpcTransport.ts
- - annotations.ts
  - casing.ts
  - enums.ts
  - extensions.ts
  - getterName.ts
  - maps.ts
  - nestedMessagesV2.ts
  - nestedMessagesV3.ts
  - oneof.ts
  - orphan.ts
  - primitivesV2.ts
  - primitivesV3.ts
  - repeatedPrimitives.ts
  - reservedWords.ts
  - wellKnownTypes.ts
- - util.ts
- mocha-check-report.js
- mocha-run-suite.js
.gitattributes
.gitignore
.npmignore
.nvmrc
.travis.yml
BUILD.bazel
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
defs.bzl
generate.js
LICENSE.txt
OWNERS
package-lock.json
package.json
README.md
release.sh
travis-ci-build.sh
tsconfig.json
tslint.json
WORKSPACE

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/improbable-eng/ts-protoc-gen

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd ts-protoc-gen

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install ts-protoc-gen

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm install ts-protoc-gen@next

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Master Build](https://travis-ci.org/improbable-eng/ts-protoc-gen.svg?branch=master)](https://travis-ci.org/improbable-eng/ts-protoc-gen)
[![NPM](https://img.shields.io/npm/v/ts-protoc-gen.svg)](https://www.npmjs.com/package/ts-protoc-gen)
[![NPM](https://img.shields.io/npm/dm/ts-protoc-gen.svg)](https://www.npmjs.com/package/ts-protoc-gen)
[![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://raw.githubusercontent.com/improbable-eng/ts-protoc-gen/master/LICENSE)

# ts-protoc-gen

> Protoc Plugin for generating TypeScript Declarations

This repository contains a [protoc](https://github.com/google/protobuf) plugin that generates TypeScript declarations
(`.d.ts` files) that match the JavaScript output of `protoc --js_out=import_style=commonjs,binary`. This plugin can
also 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).

This plugin is tested and written using TypeScript 2.7.

## Installation

### npm

As 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)).

For the latest stable version of the ts-protoc-gen plugin:

```bash
npm install ts-protoc-gen
```

For our latest build straight from master:

```bash
npm install ts-protoc-gen@next
```

### bazel

The bazel rules have been moved to a separate project [here](https://github.com/Dig-Doug/rules_typescript_proto).
There is a
[migration guide](https://github.com/Dig-Doug/rules_typescript_proto/blob/master/docs/migrating_from_ts_protoc_gen.md)
for existing users.

## Contributing

Contributions are welcome! Please refer to [CONTRIBUTING.md](https://github.com/improbable-eng/ts-protoc-gen/blob/master/CONTRIBUTING.md) for more information.

## Usage

As mentioned above, this plugin for `protoc` serves two purposes:

1. Generating TypeScript Definitions for CommonJS modules generated by protoc
2. 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).

### Generating TypeScript Definitions for CommonJS modules generated by protoc

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

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

```bash
# Path to this plugin
PROTOC_GEN_TS_PATH="./node_modules/.bin/protoc-gen-ts"

# Directory to write generated code to (.js and .d.ts files)
OUT_DIR="./generated"

protoc \
    --plugin="protoc-gen-ts=${PROTOC_GEN_TS_PATH}" \
    --js_out="import_style=commonjs,binary:${OUT_DIR}" \
    --ts_out="${OUT_DIR}" \
    users.proto base.proto
```

In 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:

```js
import { MyMessage } from "../generated/users_pb";

const msg = new MyMessage();
msg.setName("John Doe");
```

### Generating gRPC Service Stubs for use with grpc-web

[gRPC](https://grpc.io/) is a framework that enables client and server applications to communicate transparently, and makes it easier to build connected systems.

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

To 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:

```
# Path to this plugin, Note this must be an abolsute path on Windows (see #15)
PROTOC_GEN_TS_PATH="./node_modules/.bin/protoc-gen-ts"

# Directory to write generated code to (.js and .d.ts files)
OUT_DIR="./generated"

protoc \
    --plugin="protoc-gen-ts=${PROTOC_GEN_TS_PATH}" \
    --js_out="import_style=commonjs,binary:${OUT_DIR}" \
    --ts_out="service=grpc-web:${OUT_DIR}" \
    users.proto base.proto
```

The `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.

**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/).
**Note** Both `js` and `d.ts` service files will be generated regardless of whether there are service definitions in the proto files.

```js
import {
  UserServiceClient,
  GetUserRequest
} from "../generated/users_pb_service";

const client = new UserServiceClient("https://my.grpc/server");
const req = new GetUserRequest();
req.setUsername("johndoe");
client.getUser(req, (err, user) => {
  /* ... */
});
```

### Generating gRPC Service Stubs for use with grpc-node

This plugin can generate `.d.ts` files for gRPC service definitions as required by [grpc-node](https://github.com/grpc/grpc-node).

To 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:

```
# Path to this plugin, Note this must be an abolsute path on Windows (see #15)
PROTOC_GEN_TS_PATH="./node_modules/.bin/protoc-gen-ts"

# Path to the grpc_node_plugin
PROTOC_GEN_GRPC_PATH="./node_modules/.bin/grpc_tools_node_protoc_plugin"

# Directory to write generated code to (.js and .d.ts files)
OUT_DIR="./generated"

protoc \
    --plugin="protoc-gen-ts=${PROTOC_GEN_TS_PATH}" \
    --plugin=protoc-gen-grpc=${PROTOC_GEN_GRPC_PATH} \
    --js_out="import_style=commonjs,binary:${OUT_DIR}" \
    --ts_out="service=grpc-node:${OUT_DIR}" \
    --grpc_out="${OUT_DIR}" \
    users.proto base.proto
```

The `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.

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

#### Using `@grpc/grpc-js` instead of `grpc`

Add a mode parameter to generate files that import `@grpc/grpc-js` instead of `grpc`, for example:

```
--ts_out="service=grpc-node,mode=grpc-js:${OUT_DIR}"
```

You'll also need to specify the `grpc_js` option within the `--grpc_out` flag, for example:

```
--grpc_out="grpc_js:${OUT_DIR}"
```

If you're consuming the server interface types you'll need to use version `@grpc/grpc-js@1.2.0` or higher.

## Examples

- [Example output](https://github.com/improbable-eng/ts-protoc-gen/tree/master/examples) -- Code generated by `ts-protoc-gen`.
- [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.

## Gotchas

By 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:

```proto
message Example {
  uint64 bigInt = 1 [jstype = JS_STRING];
}
```