# ts-protoc-gen

> Protoc Plugin for TypeScript Declarations and Service Definitions

Latest version **0.15.0** (published 2021-04-27) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install ts-protoc-gen
pnpm add ts-protoc-gen
yarn add ts-protoc-gen
bun add ts-protoc-gen
```

Provides the command `protoc-gen-ts`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.15.0 |
| Published | 2021-04-27 |
| First published | 2017-03-26 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 174.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1394 |
| Author | Improbable |
| Maintainers | marcuslongmuir, jonnyreeves |
| Keywords | protobuf, protoc, typescript, ts, grpc, service, proto3 |

## Links

- npm: https://www.npmjs.com/package/ts-protoc-gen
- Repository: https://github.com/improbable-eng/ts-protoc-gen
- Homepage: https://github.com/improbable-eng/ts-protoc-gen#readme
- Issues: https://github.com/improbable-eng/ts-protoc-gen/issues
- npm.io page: https://npm.io/package/ts-protoc-gen

## Dependencies (1)

- [google-protobuf](https://npm.io/package/google-protobuf.md) ^3.15.5

## Alternatives

- [csv-to-markdown-table](https://npm.io/package/csv-to-markdown-table.md) — 47.0K weekly downloads
- [@sapphire/ratelimits](https://npm.io/package/@sapphire/ratelimits.md) — 4.4K weekly downloads
- [js-csvparser](https://npm.io/package/js-csvparser.md) — 2.0K weekly downloads
- [@adadapted/js-sdk](https://npm.io/package/@adadapted/js-sdk.md) — 251 weekly downloads
- [@grapecity/spread-sheets-sparklines](https://npm.io/package/@grapecity/spread-sheets-sparklines.md) — 103 weekly downloads

## Recent versions

- 0.15.0 (latest) — 2021-04-27
- 0.15.1-pre.a71b34e (next) — 2021-04-27
- 0.14.1-pre.77d9ada — 2021-04-26
- 0.14.1-pre.fd6e3a0 — 2021-04-24
- 0.14.1-pre.d492bcc — 2021-03-25
- 0.14.1-pre.e680d69 — 2020-12-15
- 0.14.1-pre.02149e6 — 2020-12-15
- 0.14.0 — 2020-12-15
- 0.13.1-pre.2e080f3 — 2020-12-10
- 0.13.0 — 2020-09-11
- 0.12.1-pre.6383416 — 2020-09-10
- 0.12.1-pre.3266132 — 2020-05-27
- 0.12.1-pre.abb949e — 2020-05-26
- 0.12.1-pre.a78a914 — 2019-10-22
- 0.12.1-pre.46e6630 — 2019-10-22
- … 85 more at https://npm.io/package/ts-protoc-gen/versions

## README

[![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)](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];
}
```

---
_Source: https://npm.io/package/ts-protoc-gen · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._