Registry / http-networking / grpc-web

grpc-web

JSON →
library2.0.2jsnpmunverified

grpc-web is the JavaScript client runtime library that enables browser-based applications to communicate with gRPC services. It functions by connecting to gRPC services through a specialized gateway proxy, such as Envoy, which has built-in gRPC-Web support. The current stable version is 2.0.2, with recent releases addressing bug fixes and minor improvements, including TypeScript compatibility updates. The project maintains a steady release cadence for bug fixes and incremental features. Key differentiators include its focus on browser environments, robust TypeScript support for generated client stubs, and the reliance on `protoc` and `protoc-gen-grpc-web` for generating client code and message definitions from `.proto` files, providing a full-stack gRPC experience for web clients.

npm install grpc-web
INSTALL
IMPORT
SIG · GRPC-WEB
G
grpc-web
http-networkingjavascriptv2.0.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

EchoServiceClient
import {EchoServiceClient} from './generated/echo_grpc_web_pb';
const {EchoServiceClient} = require('./generated/echo_grpc_web_pb.js');
This is a named import for a generated client stub. The path and name depend on your `.proto` file and `protoc-gen-grpc-web` output options. CommonJS `require` is also supported if `import_style=commonjs` was used during generation.
EchoRequest
import {EchoRequest} from './generated/echo_pb';
const {EchoRequest} = require('./generated/echo_pb.js');
This is a named import for a generated message type. The path and name depend on your `.proto` file and `protoc` output options. CommonJS `require` is also supported if `import_style=commonjs` was used during generation.
grpcWeb
import * as grpcWeb from 'grpc-web';
import { GrpcWebClient } from 'grpc-web';
The main library is imported as a namespace, commonly aliased as `grpcWeb` or `grpc`. Specific classes like `RpcError` and `Status` are accessed via this namespace (e.g., `grpcWeb.RpcError`).
RpcError
import * as grpcWeb from 'grpc-web'; /* ... */ (err: grpcWeb.RpcError) => { /* ... */ }
RpcError is typically used as a type annotation in callbacks. Introduced as an improved error type in v1.3.0.

This quickstart demonstrates how to instantiate a gRPC-Web client, create a request, send it to a gRPC service through a proxy, and handle the response and potential errors using TypeScript.

import * as grpcWeb from 'grpc-web'; import { EchoServiceClient } from './generated/echo_grpc_web_pb'; import { EchoRequest, EchoResponse } from './generated/echo_pb'; // Ensure you have a gRPC-Web proxy (e.g., Envoy) running at this address const GRPC_PROXY_ADDRESS = 'http://localhost:8080'; // Create a client instance for your gRPC service const echoService = new EchoServiceClient(GRPC_PROXY_ADDRESS, null, null); // Create a new request message const request = new EchoRequest(); request.setMessage('Hello from gRPC-Web!'); // Define custom metadata (optional) const metadata = { 'custom-header-1': 'value1' }; // Make the gRPC call const call = echoService.echo( request, metadata, (err: grpcWeb.RpcError, response: EchoResponse) => { if (err) { console.error('Error during gRPC call:', err.code, err.message); return; } console.log('Received message:', response.getMessage()); } ); // Handle status updates (optional, for streaming or status monitoring) call.on('status', (status: grpcWeb.Status) => { if (status.code !== grpcWeb.StatusCode.OK) { console.warn('gRPC call status:', status.code, status.details); } else { console.info('gRPC call completed successfully.'); } }); // Handle stream errors (for server streaming, optional) call.on('error', (err: grpcWeb.RpcError) => { console.error('Stream error:', err.message); });
Debug
Known issues
breakingEnums generated for TypeScript versions older than 5.9 might encounter compatibility issues, leading to compilation errors or unexpected runtime behavior.
fix
Upgrade `grpc-web` to version 2.0.2 or newer to ensure compatibility with TypeScript 5.9+ through the use of regular enums in generated code. Regenerate your client stubs with the latest `protoc-gen-grpc-web`.
affects: <=2.0.1
gotchagRPC-Web clients cannot directly connect to standard gRPC servers. An intermediary proxy (e.g., Envoy, or a gRPC-Web enabled Node.js proxy) is strictly required to translate between the gRPC-Web protocol used by browsers and the HTTP/2 gRPC protocol used by servers.
fix
Ensure you have a gRPC-Web compatible proxy configured and running between your browser client and your gRPC backend. Refer to the gRPC-Web documentation for proxy setup instructions, typically using Envoy.
affects: >=1.0.0
gotchaGenerating client stubs and message definitions requires both `protoc` (Protocol Buffers compiler) and `protoc-gen-grpc-web` (gRPC-Web plugin) to be installed and accessible in your system's PATH. Incorrect versions or missing executables will lead to generation failures.
fix
Download and install `protoc` from the official Protocol Buffers releases and `protoc-gen-grpc-web` from the gRPC-Web GitHub releases. Ensure both executables are in your system's PATH and have appropriate permissions.
affects: >=1.0.0
gotchaWhen generating TypeScript client stubs, choosing `import_style=commonjs+dts` provides CommonJS-style JavaScript files with separate `.d.ts` declaration files, while `import_style=typescript` provides full TypeScript output. Mixing these or using an inappropriate style can lead to import errors or type mismatches.
fix
Consistently use either `import_style=commonjs+dts` or `import_style=typescript` for `protoc-gen-grpc-web`. For modern TypeScript projects, `import_style=typescript` is often preferred. Ensure your `tsconfig.json` compiler options are compatible with the chosen import style.
affects: >=1.0.0
Errors
Common errors & fixes
protoc-gen-grpc-web: program not found or is not executable
The `protoc-gen-grpc-web` plugin is either not installed, not in the system's PATH, or lacks execute permissions.
fix
Download `protoc-gen-grpc-web` from the GitHub releases page, place it in a directory included in your system's PATH, and ensure it has execute permissions (e.g., `chmod +x protoc-gen-grpc-web`).
TypeError: Cannot read properties of undefined (reading 'ClientReadableStream')
This often indicates that the `grpc-web` runtime library is not correctly imported or bundled, or that the generated client stub is trying to access `grpc.web` properties that are not available.
fix
Ensure `import * as grpcWeb from 'grpc-web';` is present and that your bundling tool (webpack, Parcel, Rollup) correctly includes the `grpc-web` library in your final output. Verify your `protoc-gen-grpc-web` output options match your project's module system (CommonJS/ESM).
CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
The gRPC-Web proxy (e.g., Envoy) or the backend server is not correctly configured to handle Cross-Origin Resource Sharing (CORS) preflight requests from your web application's origin.
fix
Configure your gRPC-Web proxy (e.g., Envoy's CORS filter) to include the `Access-Control-Allow-Origin` header with the appropriate value (e.g., your frontend's URL or `*` for development) and allow necessary HTTP methods (POST, OPTIONS) and headers.
Upgrade
Version history
2.0.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources