# grpc-web

> gRPC-Web Client Runtime Library

Latest version **2.1.1** (published 2026-08-27) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install grpc-web
pnpm add grpc-web
yarn add grpc-web
bun add grpc-web
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.1.1 |
| Published | 2026-08-27 |
| First published | 2018-08-02 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 64.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9260 |
| Author | Google Inc. |
| Maintainers | stanleycheung, sampajano, vuhag123 |

## Links

- npm: https://www.npmjs.com/package/grpc-web
- Repository: https://github.com/grpc/grpc-web
- Homepage: https://grpc.io/
- Issues: https://github.com/grpc/grpc-web/issues
- npm.io page: https://npm.io/package/grpc-web

## Recent versions

- 2.1.1 (latest) — 2026-08-27
- 2.1.0 (rc) — 2026-08-04
- 2.0.2 — 2025-09-16
- 2.0.1 — 2025-09-05
- 2.0.0 — 2025-08-27
- 1.5.0 — 2023-11-09
- 1.4.2 — 2022-10-28
- 1.4.1 — 2022-09-28
- 1.4.0 — 2022-09-23
- 1.3.1 — 2022-01-29
- 1.3.1-rc — 2021-11-19
- 1.3.0 — 2021-10-14
- 1.2.1 — 2020-08-18
- 1.2.0 — 2020-06-22
- 1.1.0 — 2020-05-28
- … 12 more at https://npm.io/package/grpc-web/versions

## README

# gRPC-Web Client Runtime Library

gRPC-Web provides a Javascript library that lets browser clients access a gRPC
service. You can find out much more about gRPC in its own
[website](https://grpc.io).

gRPC-Web is now Generally Available, and considered stable enough for production use.

gRPC-Web clients connect to gRPC services via a special gateway proxy: the
current version of the library uses [Envoy](https://www.envoyproxy.io/) by
default, in which gRPC-Web support is built-in.

In the future, we expect gRPC-Web to be supported in language-specific Web
frameworks, such as Python, Java, and Node. See the
[roadmap](https://github.com/grpc/grpc-web/blob/master/doc/roadmap.md) doc.


## Quick Start

This example is using the `echo.proto` file from the
[Echo Example](https://github.com/grpc/grpc-web/tree/master/net/grpc/gateway/examples/echo).

 1. Add `grpc-web` as a dependency using `npm`.

```sh
$ npm i grpc-web
```

 2. Download `protoc` and the `protoc-gen-grpc-web` protoc plugin.

You can download the `protoc` binary from the official
[protocolbuffers](https://github.com/protocolbuffers/protobuf/releases)
release page.

You can download the `protoc-gen-grpc-web` protoc plugin from our Github
[release](https://github.com/grpc/grpc-web/releases) page.


Make sure they are both executable and are discoverable from your PATH.


 3. Generate your proto messages and the service client stub classes with
`protoc` and the `protoc-gen-grpc-web` plugin. You can set the
`import_style=commonjs` option for both `--js_out` and `--grpc-web_out`.

```sh
$ protoc -I=$DIR echo.proto \
--js_out=import_style=commonjs:generated \
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:generated
```

 4. Start using your generated client!

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

const client = new EchoServiceClient('localhost:8080');

const request = new EchoRequest();
request.setMessage('Hello World!');

const metadata = {'custom-header-1': 'value1'};

client.echo(request, metadata, (err, response) => {
  // ...
});
```


## What's Next

To complete the example, you need to run a proxy that understands the
[gRPC-Web protocol](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2)
between your browser client and your gRPC service. The default proxy currently
is [Envoy](https://www.envoyproxy.io/). Please visit our
[Github repo](https://github.com/grpc/grpc-web) for more information.

Here's a quick way to get started!

```sh
$ git clone https://github.com/grpc/grpc-web
$ cd grpc-web
$ docker-compose up node-server envoy commonjs-client
```

Open a browser tab, and go to:

```
http://localhost:8081/echotest.html
```

## TypeScript Support

The `grpc-web` module can now be imported as a TypeScript module. This is
currently an experimental feature. Any feedback welcome!

When using the `protoc-gen-grpc-web` protoc plugin, mentioned above, pass in
either:

 - `import_style=commonjs+dts`: existing CommonJS style stub + `.d.ts` typings
 - `import_style=typescript`: full TypeScript output


```ts
import * as grpcWeb from 'grpc-web';
import {EchoServiceClient} from './echo_grpc_web_pb';
import {EchoRequest, EchoResponse} from './echo_pb';

const echoService = new EchoServiceClient('http://localhost:8080', null, null);

const request = new EchoRequest();
request.setMessage('Hello World!');

const call = echoService.echo(request, {'custom-header-1': 'value1'},
  (err: grpcWeb.RpcError, response: EchoResponse) => {
    console.log(response.getMessage());
  });
call.on('status', (status: grpcWeb.Status) => {
  // ...
});
```

See a full TypeScript example
[here](https://github.com/grpc/grpc-web/blob/master/net/grpc/gateway/examples/echo/ts-example/client.ts).


## Run Tests

Pre-requisites:
 - `protoc`
 - `protoc-gen-grpc-web` plugin


```sh
$ npm test
```

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