Registry / devops / protoc-gen-grpc-gateway-es

protoc-gen-grpc-gateway-es

library0.4.0jsnpmunverified

A protoc plugin that generates TypeScript client code for gRPC APIs exposed via grpc-gateway, powered by protobuf-es framework and bun toolchain. Version 0.4.0 integrates with buf build system, converting protobuf messages to TypeScript types and RPCs to JavaScript classes with fetch-ready Request objects. Unlike alternatives, it minimizes runtime dependencies and provides type aliases for bytes, int64, duration, and timestamp types. Requires protoc and grpc-gateway annotations (google.api.http).

devops

npm install protoc-gen-grpc-gateway-es

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PROTOC-GEN-GRPC-GA

protoc-gen-grpc-gateway-es

devopsjavascriptv0.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

generateGrpcGateway

✓ npx protoc-gen-grpc-gateway-es

✗ protoc-gen-grpc-gateway-es (without npx)

The plugin is invoked as a binary via npx; not imported as a library. Ensure npx is available.

RPC

✓ import { RPC } from './path/to/generated/runtime'

✗ const RPC = require('./path/to/generated/runtime')

Generated runtime.ts exports RPC class and type aliases. Import using ESM syntax.

BytesString

✓ import { BytesString } from './path/to/generated/runtime'

✗ import { bytesString } from './path/to/generated/runtime'

Type alias for base64-encoded bytes. Case-sensitive: BytesString with capital B.

BigIntString

✓ import { BigIntString } from './path/to/generated/runtime'

✗ type BigIntString = string

Type alias for int64 values as string. Use the generated helper to convert to BigInt.

GrpcGatewayPluginConfig

✓ import { GrpcGatewayPluginConfig } from 'protoc-gen-grpc-gateway-es'

Configuration type for the plugin, available via package import.

Setup and usage of protoc-gen-grpc-gateway-es with Buf to generate TypeScript client for gRPC-gateway.

// 1. Install the plugin npm install --save-dev protoc-gen-grpc-gateway-es // 2. In buf.gen.yaml, configure the plugin // version: v1 // plugins: // - plugin: ./path/to/your/script.sh // out: gen/ts // 3. Create a shell script (e.g., protoc-gen-grpc-gateway-es.sh): #!/bin/sh npx protoc-gen-grpc-gateway-es "$@" // 4. Make executable and run buf generate chmod +x protoc-gen-grpc-gateway-es.sh buf generate // 5. Use generated client import { createClient } from './gen/ts/path/to/service_pb'; import { RPC } from './gen/ts/runtime'; const client = createClient('https://api.example.com'); const response = await client.sayHello({ name: 'World' });

Debug

Known issues

breakingPlugin requires Node.js 16+ and bun toolchain for runtime generation

fix

Ensure Node.js >=16 and bun are installed. Use npx to invoke the plugin.

affects: >=0.4.0

gotchaGenerated runtime.ts uses ESM modules; CommonJS require() will not work

fix

Set type: 'module' in package.json or use dynamic import() if using CommonJS.

affects: >=0.4.0

gotchagoogle.protobuf.Timestamp fields are strings (ISO-8601), not Date objects

fix

Convert to Date: new Date(timestampString). For serialization, use date.toISOString().

affects: >=0.4.0

gotchaint64 fields are represented as string (BigIntString) to avoid precision loss

fix

Use runtime helpers to convert between BigInt and string. Do not parse as number.

affects: >=0.4.0

gotchabytes fields are base64-encoded strings, not Uint8Array

fix

Use runtime.ts helper functions for conversion: bytesToBase64, base64ToBytes.

affects: >=0.4.0

Errors

Common errors & fixes

Error: Cannot find module 'protoc-gen-grpc-gateway-es'

The plugin binary is not found in PATH or not installed

fix

Install as devDependency: npm install --save-dev protoc-gen-grpc-gateway-es

error: TypeScript cannot find module './gen/ts/runtime'

Generated runtime.ts is not in the expected output directory or missing

fix

Ensure buf.gen.yaml output path matches the import path. Check that plugin runs successfully.

Type 'Request' is not assignable to type 'ResponseMessage'

Using response directly without calling responseTypeId or proper parsing

fix

Use RPC.responseTypeId to cast the response JSON to the correct type.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

@bufbuild/protobufrequiredRequired for protobuf message types and runtime conversion

typescriptoptionalGenerated code contains TypeScript types

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/h2oai/protoc-gen-grpc-gateway-es ↗

packageprotoc-gen-grpc-gateway-es ↗

homepagehttps://github.com/h2oai/protoc-gen-grpc-gateway-es#readme ↗