gRPC-Web Client Runtime Library

Common errors

• protoc-gen-grpc-web: program not found or is not executable

  cause 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')

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

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

Warnings

• breaking Enums 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`.
• gotcha gRPC-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.
• gotcha Generating 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.
• gotcha When 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.

Install

• npm install grpc-web npm
• yarn add grpc-web yarn
• pnpm add grpc-web pnpm

Imports

• EchoServiceClient
  wrong:

  const {EchoServiceClient} = require('./generated/echo_grpc_web_pb.js');

  correct:

  import {EchoServiceClient} from './generated/echo_grpc_web_pb';

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

  const {EchoRequest} = require('./generated/echo_pb.js');

  correct:

  import {EchoRequest} from './generated/echo_pb';

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

  import { GrpcWebClient } from 'grpc-web';

  correct:

  import * as grpcWeb 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.

Quickstart

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);
});