TypeScript icon, indicating that this package has built-in type declarations

    1.0.5 • Public • Published

    nice-grpc-web npm version

    A Browser gRPC client library that is nice to you. Built on top of @improbable-eng/grpc-web.


    • Written in TypeScript for TypeScript.
    • Modern API that uses Promises and Async Iterables for streaming.
    • Cancelling calls using AbortSignal.
    • Middleware support via concise API that uses Async Generators.


    npm install nice-grpc-web


    Compiling Protobuf files

    The recommended way is to use ts-proto.

    Using ts-proto

    Install necessary tools:

    npm install protobufjs long
    npm install --save-dev grpc-tools ts-proto

    Given a Protobuf file ./proto/example.proto, generate TypeScript code into directory ./compiled_proto:

    ./node_modules/.bin/grpc_tools_node_protoc \
      --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto \
      --ts_proto_out=./compiled_proto \
      --ts_proto_opt=env=browser,outputServices=generic-definitions,outputJsonMethods=false,useExactTypes=false \
      --proto_path=./proto \

    You can omit the --plugin flag if you invoke this command via npm script.

    Using google-protobuf

    Install necessary tools:

    npm install google-protobuf
    npm install --save-dev grpc-tools ts-protoc-gen @types/google-protobuf

    Given a Protobuf file ./proto/example.proto, generate JS code and TypeScript definitions into directory ./compiled_proto:

    ./node_modules/.bin/grpc_tools_node_protoc \
      --plugin=protoc-gen-ts=./node_modules/.bin/protoc-gen-ts \
      --js_out=import_style=commonjs,binary:./compiled_proto \
      --ts_out=service=grpc-web:./compiled_proto \
      --proto_path=./proto \

    Preparing the server

    Browsers can't talk directly to a gRPC server, so a proxy is required.

    It is recommended to use Envoy proxy with grpc_web filter.

    In Kubernetes, use Contour ingress controller, which is based on Envoy and has grpc_web filter enabled by default.

    Note that with Envoy, only unary and server streaming calls are supported. If you require client streaming and bidirectional streaming calls, use grpcwebproxy and websocket transport.


    Consider the following Protobuf definition:

    syntax = "proto3";
    package nice_grpc.example;
    service ExampleService {
      rpc ExampleUnaryMethod(ExampleRequest) returns (ExampleResponse) {};
    message ExampleRequest {
      // ...
    message ExampleResponse {
      // ...

    After compiling Protobuf file, we can create the client:

    When compiling Protobufs using ts-proto:

    import {createChannel, createClient} from 'nice-grpc-web';
    import {ExampleServiceDefinition} from './compiled_proto/example';
    const channel = createChannel('http://localhost:8080');
    const client: Client<typeof ExampleServiceDefinition> = createClient(

    When compiling Protobufs using google-protobuf:

    import {createChannel, createClient, Client} from 'nice-grpc';
    import {
    } from './compiled_proto/example_grpc_pb';
    const channel = createChannel('http://localhost:8080');
    const client: Client<IExampleService> = createClient(ExampleService, channel);

    Further examples use ts-proto.

    Call the method:

    const response = await client.exampleUnaryMethod(request);

    With ts-proto, request is automatically wrapped with fromPartial.

    Call options

    Each client method accepts CallOptions as an optional second argument, that has type:

    type CallOptions = {
       * Request metadata.
      metadata?: Metadata;
       * Signal that cancels the call once aborted.
      signal?: AbortSignal;
       * Called when header is received.
      onHeader?(header: Metadata): void;
       * Called when trailer is received.
      onTrailer?(trailer: Metadata): void;

    Call options may be augmented by Middleware.

    When creating a client, you may specify default call options per method, or for all methods. This doesn't make much sense for built-in options, but may do for middleware.

    const client = createClient(ExampleServiceDefinition, channel, {
      '*': {
        // applies for all methods
      exampleUnaryMethod: {
        // applies for single method


    A channel is constructed from an address and optional transport. The following are equivalent:

    import {createChannel} from 'nice-grpc-web';
    import {grpc} from '@improbable-eng/grpc-web';
    createChannel('', grpc.CrossBrowserHttpTransport());

    If the port is omitted, it defaults to 80 for http, and 443 for https.


    Client can send request metadata and receive response header and trailer:

    import {Metadata} from 'nice-grpc-web';
    const response = await client.exampleUnaryMethod(request, {
      metadata: Metadata({key: 'value'}),
      onHeader(header: Metadata) {
        // ...
      onTrailer(trailer: Metadata) {
        // ...


    Client calls may throw gRPC errors represented as ClientError, that contain status code and description.

    import {ClientError, Status} from 'nice-grpc-web';
    import {ExampleResponse} from './compiled_proto/example';
    let response: ExampleResponse | null;
    try {
      response = await client.exampleUnaryMethod(request);
    } catch (error: unknown) {
      if (error instanceof ClientError && error.code === Status.NOT_FOUND) {
        response = null;
      } else {
        throw error;

    Cancelling calls

    A client call can be cancelled using AbortSignal.

    import AbortController from 'node-abort-controller';
    import {isAbortError} from 'abort-controller-x';
    const abortController = new AbortController();
      .exampleUnaryMethod(request, {
        signal: abortController.signal,
      .catch(error => {
        if (isAbortError(error)) {
          // aborted
        } else {
          throw error;

    Server streaming

    Consider the following Protobuf definition:

    service ExampleService {
      rpc ExampleStreamingMethod(ExampleRequest)
        returns (stream ExampleResponse) {};

    Client method returns an Async Iterable:

    for await (const response of client.exampleStreamingMethod(request)) {
      // ...

    Client streaming

    Given a client streaming method:

    service ExampleService {
      rpc ExampleClientStreamingMethod(stream ExampleRequest)
        returns (ExampleResponse) {};

    Client method expects an Async Iterable as its first argument:

    import {ExampleRequest, DeepPartial} from './compiled_proto/example';
    async function* createRequest(): AsyncIterable<DeepPartial<ExampleRequest>> {
      for (let i = 0; i < 10; i++) {
        yield request;
    const response = await client.exampleClientStreamingMethod(createRequest());


    Client middleware intercepts outgoing calls allowing to:

    • Execute any logic before and after reaching server
    • Modify request metadata
    • Look into request, response and response metadata
    • Send call multiple times for retries or hedging
    • Augment call options type to have own configuration

    Client middleware is defined as an Async Generator. The most basic no-op middleware looks like this:

    import {ClientMiddlewareCall, CallOptions} from 'nice-grpc-web';
    async function* middleware<Request, Response>(
      call: ClientMiddlewareCall<Request, Response>,
      options: CallOptions,
    ) {
      return yield*, options);

    For unary and client streaming methods, the generator yields no items and returns a single response; for server streaming and bidirectional streaming methods, it yields each response and returns void. By doing return yield* we cover both cases. To handle these cases separately, we can write a middleware as follows:

    async function* middleware<Request, Response>(
      call: ClientMiddlewareCall<Request, Response>,
      options: CallOptions,
    ) {
      if (!call.responseStream) {
        const response = yield*, options);
        return response;
      } else {
        for await (const response of, options)) {
          yield response;

    To create a client with middleware, use a client factory:

    import {createClientFactory} from 'nice-grpc-web';
    const client = createClientFactory()
      .create(ExampleService, channel);

    A middleware that is attached first, will be invoked last.

    You can reuse a single factory to create multiple clients:

    const clientFactory = createClientFactory().use(middleware);
    const client1 = clientFactory.create(Service1, channel1);
    const client2 = clientFactory.create(Service2, channel2);

    You can also attach middleware per-client:

    const factory = createClientFactory().use(middlewareA);
    const client1 = clientFactory.use(middlewareB).create(Service1, channel1);
    const client2 = clientFactory.use(middlewareC).create(Service2, channel2);

    In the above example, Service1 client gets middlewareA and middlewareB, and Service2 client gets middlewareA and middlewareC.

    Example: Logging

    Log all calls:

    import {
    } from 'nice-grpc-web';
    import {isAbortError} from 'abort-controller-x';
    async function* loggingMiddleware<Request, Response>(
      call: ClientMiddlewareCall<Request, Response>,
      options: CallOptions,
    ) {
      const {path} = call.method;
      console.log('Client call', path, 'start');
      try {
        const result = yield*, options);
        console.log('Client call', path, 'end: OK');
        return result;
      } catch (error) {
        if (error instanceof ClientError) {
            'Client call',
            `end: ${Status[error.code]}: ${error.details}`,
        } else if (isAbortError(error)) {
          console.log('Client call', path, 'cancel');
        } else {
          console.log('Client call', path, `error: ${error?.stack}`);
        throw error;


    npm i nice-grpc-web

    DownloadsWeekly Downloads






    Unpacked Size

    113 kB

    Total Files


    Last publish


    • aikoven