[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-10808":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":28,"readmeContent":29,"aiSummary":30,"trendingCount":16,"starSnapshotCount":16,"syncStatus":31,"lastSyncTime":32,"discoverSource":33},10808,"grpc-web","grpc\u002Fgrpc-web","grpc","gRPC for Web Clients","https:\u002F\u002Fgrpc.io",null,"JavaScript",9223,796,190,181,0,6,19,5,39.7,"Apache License 2.0",false,"master",true,[7,26,27],"javascript","web","2026-06-12 02:02:26","# gRPC Web · [![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fgrpc-web.svg?style=flat)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fgrpc-web)\n\nA JavaScript implementation of [gRPC][] for browser clients. For more information,\nincluding a **quick start**, see the [gRPC-web documentation][grpc-web-docs].\n\ngRPC-web clients connect to gRPC services via a special proxy; by default,\ngRPC-web uses [Envoy][].\n\nIn the future, we expect gRPC-web to be supported in language-specific web\nframeworks for languages such as Python, Java, and Node. For details, see the\n[roadmap](doc\u002Froadmap.md).\n\n## Streaming Support\ngRPC-web currently supports 2 RPC modes:\n- Unary RPCs ([example](#make-a-unary-rpc-call))\n- Server-side Streaming RPCs ([example](#server-side-streaming)) (NOTE: Only when [`grpcwebtext`](#wire-format-mode) mode is used.)\n\nClient-side and Bi-directional streaming is not currently supported (see [streaming roadmap](doc\u002Fstreaming-roadmap.md)).\n\n## Quick Start\n\nEager to get started? Try the [Hello World example][]. From this example, you'll\nlearn how to do the following:\n\n - Define your service using protocol buffers\n - Implement a simple gRPC Service using Node.js\n - Configure the Envoy proxy\n - Generate protobuf message classes and client service stub for the client\n - Compile all the JS dependencies into a static library that can be consumed\n   by the browser easily\n\n## Advanced Demo: Browser Echo App\n\nYou can also try to run a more advanced Echo app from the browser with a\nstreaming example.\n\nFrom the repo root directory:\n\n```sh\n$ docker-compose pull prereqs node-server envoy commonjs-client\n$ docker-compose up node-server envoy commonjs-client\n```\n\nOpen a browser tab, and visit http:\u002F\u002Flocalhost:8081\u002Fechotest.html.\n\nTo shutdown: `docker-compose down`.\n\n## Runtime Library\n\nThe gRPC-web runtime library is available on npm:\n\n```sh\n$ npm i grpc-web\n```\n\n## Code Generator Plugins\n\n### (Prerequisite) 1. Protobuf (`protoc`)\n\nIf you don't already have [`protoc`](https:\u002F\u002Fgithub.com\u002Fprotocolbuffers\u002Fprotobuf)\ninstalled, download it first from [here](https:\u002F\u002Fgithub.com\u002Fprotocolbuffers\u002Fprotobuf\u002Freleases) and install it on your PATH.\n\nIf you use Homebrew (on macOS), you could run:\n\n```sh\nbrew install protobuf\n```\n\n### (Prerequisite) 2. Protobuf-javascript (`protoc-gen-js`)\n\nIf you don't have [`protoc-gen-js`](https:\u002F\u002Fgithub.com\u002Fprotocolbuffers\u002Fprotobuf-javascript) installed, download it from [protocolbuffers\u002Fprotobuf-javascript](https:\u002F\u002Fgithub.com\u002Fprotocolbuffers\u002Fprotobuf-javascript\u002Freleases) and install it on your PATH.\n\nOr, use the [third-party](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fprotoc-gen-js) npm installer:\n\n```\nnpm install -g protoc-gen-js\n```\n\n### 3. Install gRPC-Web Code Generator\n\nYou can download the `protoc-gen-grpc-web` protoc plugin from our\n[release](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc-web\u002Freleases) page:\n\nMake sure all executables are discoverable from your PATH.\n\nFor example, on macOS, you can do:\n\n```sh\nsudo mv protoc-gen-grpc-web-2.0.2-darwin-aarch64 \\\n    \u002Fusr\u002Flocal\u002Fbin\u002Fprotoc-gen-grpc-web\n\nchmod +x \u002Fusr\u002Flocal\u002Fbin\u002Fprotoc-gen-grpc-web\n```\n\nNote: If you are using our Docker setup, the `prereqs` image already includes\nboth `protoc` and the `protoc-gen-grpc-web` plugin on the PATH.\n\n### (Optional) 4. Verify Installations\n\nYou can optionally verify the plugins work by following our [Hello World example](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc-web\u002Ftree\u002Fmaster\u002Fnet\u002Fgrpc\u002Fgateway\u002Fexamples\u002Fhelloworld#generating-stubs):\n\n```sh\ncd net\u002Fgrpc\u002Fgateway\u002Fexamples\u002Fhelloworld\n\nprotoc -I=. helloworld.proto \\\n  --js_out=import_style=commonjs:. \\\n  --grpc-web_out=import_style=commonjs,mode=grpcwebtext:.\n```\n\nAfter the command runs successfully, you should now see two new files generated\nin the current directory. By running:\n\n```\nls -1 *_pb.js\n```\n\nInstallation is successful if you see the following 2 files:\n\n - `helloworld_pb.js` — Generated by `protoc-gen-js` plugin\n - `helloworld_grpc_web_pb.js` - Generated by gRPC-Web plugin\n\n## Client Configuration Options\n\nTypically, you will run the following command to generate the proto messages\nand the service client stub from your `.proto` definitions:\n\n```sh\nprotoc -I=$DIR echo.proto \\\n  --js_out=import_style=commonjs:$OUT_DIR \\\n  --grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR\n```\n\nYou can then use Browserify, Webpack, Closure Compiler, etc. to resolve imports\nat compile time.\n\n### Import Style\n\n`import_style=closure`: The default generated code has\n[Closure](https:\u002F\u002Fdevelopers.google.com\u002Fclosure\u002Flibrary\u002F) `goog.require()`\nimport style.\n\n`import_style=commonjs`: The\n[CommonJS](https:\u002F\u002Frequirejs.org\u002Fdocs\u002Fcommonjs.html) style `require()` is\nalso supported.\n\n`import_style=commonjs+dts`: (Experimental) In addition to above, a `.d.ts`\ntypings file will also be generated for the protobuf messages and service stub.\n\n`import_style=typescript`: (Experimental) The service stub will be generated\nin TypeScript. See **TypeScript Support** below for information on how to\ngenerate TypeScript files.\n\n> **Note:** The `commonjs+dts` and `typescript` styles are only supported by\n`--grpc-web_out=import_style=...`, not by `--js_out=import_style=...`.\n\n### Wire Format Mode\n\nFor more information about the gRPC-web wire format, see the\n[specification](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc\u002Fblob\u002Fmaster\u002Fdoc\u002FPROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2).\n\n`mode=grpcwebtext`: The default generated code sends the payloads in the\n`grpc-web-text` format.\n\n  - `Content-Type: application\u002Fgrpc-web-text`\n  - Payloads are base64-encoded.\n  - Both unary and server streaming calls are supported.\n\n`mode=grpcweb`: A binary protobuf format is also supported.\n\n  - `Content-Type: application\u002Fgrpc-web+proto`\n  - Payloads are in the binary protobuf format.\n  - Only unary calls are supported.\n\n## How It Works\n\nLet's take a look at how gRPC-web works with a simple example. You can find out\nhow to build, run and explore the example yourself in\n[Build and Run the Echo Example](net\u002Fgrpc\u002Fgateway\u002Fexamples\u002Fecho).\n\n### 1. Define your service\n\nThe first step when creating any gRPC service is to define it. Like all gRPC\nservices, gRPC-web uses\n[protocol buffers](https:\u002F\u002Fdevelopers.google.com\u002Fprotocol-buffers) to define\nits RPC service methods and their message request and response types.\n\n```protobuf\nmessage EchoRequest {\n  string message = 1;\n}\n\n...\n\nservice EchoService {\n  rpc Echo(EchoRequest) returns (EchoResponse);\n\n  rpc ServerStreamingEcho(ServerStreamingEchoRequest)\n      returns (stream ServerStreamingEchoResponse);\n}\n```\n\n### 2. Run the server and proxy\n\nNext you need to have a gRPC server that implements the service interface and a\ngateway proxy that allows the client to connect to the server. Our example\nbuilds a simple Node gRPC backend server and the Envoy proxy.\n\nFor the Echo service: see the\n[service implementation](net\u002Fgrpc\u002Fgateway\u002Fexamples\u002Fecho\u002Fnode-server\u002Fserver.js).\n\nFor the Envoy proxy: see the\n[config YAML file](net\u002Fgrpc\u002Fgateway\u002Fexamples\u002Fecho\u002Fenvoy.yaml).\n\n### 3. Write your JS client\n\nOnce the server and gateway are up and running, you can start making gRPC calls\nfrom the browser!\n\nCreate your client:\n\n```js\nvar echoService = new proto.mypackage.EchoServiceClient(\n  'http:\u002F\u002Flocalhost:8080');\n```\n\n#### Make a unary RPC call:\n\n```js\nvar request = new proto.mypackage.EchoRequest();\nrequest.setMessage(msg);\nvar metadata = {'custom-header-1': 'value1'};\nechoService.echo(request, metadata, function(err, response) {\n  if (err) {\n    console.log(err.code);\n    console.log(err.message);\n  } else {\n    console.log(response.getMessage());\n  }\n});\n```\n\n#### Server-side streaming:\n\n```js\nvar stream = echoService.serverStreamingEcho(streamRequest, metadata);\nstream.on('data', function(response) {\n  console.log(response.getMessage());\n});\nstream.on('status', function(status) {\n  console.log(status.code);\n  console.log(status.details);\n  console.log(status.metadata);\n});\nstream.on('end', function(end) {\n  \u002F\u002F stream end signal\n});\n\n\u002F\u002F to close the stream\nstream.cancel();\n```\n\nFor an in-depth tutorial, see [this\npage](net\u002Fgrpc\u002Fgateway\u002Fexamples\u002Fecho\u002Ftutorial.md).\n\n## Setting a Deadline\n\nYou can set a deadline for your RPC by setting a `deadline` header. The value\nshould be a Unix timestamp, in milliseconds.\n\n```js\nvar deadline = new Date();\ndeadline.setSeconds(deadline.getSeconds() + 1);\n\nclient.sayHelloAfterDelay(request, {deadline: deadline.getTime().toString()},\n  (err, response) => {\n    \u002F\u002F err will be populated if the RPC exceeds the deadline\n    ...\n  });\n```\n\n## TypeScript Support\n\nThe `grpc-web` module can now be imported as a TypeScript module. This is\ncurrently an experimental feature. Any feedback welcome!\n\nWhen using the `protoc-gen-grpc-web` protoc plugin, mentioned above, pass in\neither:\n\n - `import_style=commonjs+dts`: existing CommonJS style stub + `.d.ts` typings\n - `import_style=typescript`: full TypeScript output\n\nDo *not* use `import_style=typescript` for `--js_out`, it will silently be\nignored. Instead you should use `--js_out=import_style=commonjs`, or\n`--js_out=import_style=commonjs,binary` if you are using `mode=grpcweb`. The\n`--js_out` plugin will generate JavaScript code (`echo_pb.js`), and the\n`-grpc-web_out` plugin will generate a TypeScript definition file for it\n(`echo_pb.d.ts`). This is a temporary hack until the `--js_out` supports\nTypeScript itself.\n\nFor example, this is the command you should use to generate TypeScript code\nusing the binary wire format:\n\n```sh\nprotoc -I=$DIR echo.proto \\\n  --js_out=import_style=commonjs,binary:$OUT_DIR \\\n  --grpc-web_out=import_style=typescript,mode=grpcweb:$OUT_DIR\n```\n\nIt will generate the following files:\n\n* `EchoServiceClientPb.ts` - Generated by `--grpc-web_out`, contains the\nTypeScript gRPC-web code.\n* `echo_pb.js` - Generated by `--js_out`, contains the JavaScript Protobuf\ncode.\n* `echo_pb.d.ts` - Generated by `--grpc-web_out`, contains TypeScript\ndefinitions for `echo_pb.js`.\n\n### Using Callbacks\n\n```ts\nimport * as grpcWeb from 'grpc-web';\nimport {EchoServiceClient} from '.\u002FEchoServiceClientPb';\nimport {EchoRequest, EchoResponse} from '.\u002Fecho_pb';\n\nconst echoService = new EchoServiceClient('http:\u002F\u002Flocalhost:8080', null, null);\n\nconst request = new EchoRequest();\nrequest.setMessage('Hello World!');\n\nconst call = echoService.echo(request, {'custom-header-1': 'value1'},\n  (err: grpcWeb.RpcError, response: EchoResponse) => {\n    console.log(response.getMessage());\n  });\ncall.on('status', (status: grpcWeb.Status) => {\n  \u002F\u002F ...\n});\n```\n\n(See [here](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc-web\u002Fblob\u002F4d7dc44c2df522376394d3e3315b7ab0e010b0c5\u002Fpackages\u002Fgrpc-web\u002Findex.d.ts#L29-L39) for the full list of possible `.on(...)` callbacks.)\n\n### (Optional) Using Promises (Limited Features)\n\n> **NOTE:** It is not possible to access the `.on(...)` callbacks (e.g. for `metadata` and `status`) when Promise is used.\n\n```ts\n\u002F\u002F Create a Promise client instead\nconst echoService = new EchoServicePromiseClient('http:\u002F\u002Flocalhost:8080', null, null);\n\n... (same as above)\n\nthis.echoService.echo(request, {'custom-header-1': 'value1'})\n  .then((response: EchoResponse) => {\n    console.log(`Received response: ${response.getMessage()}`);\n  }).catch((err: grpcWeb.RpcError) => {\n    console.log(`Received error: ${err.code}, ${err.message}`);\n  });\n```\n\nFor the full TypeScript example, see\n[ts-example\u002Fclient.ts](net\u002Fgrpc\u002Fgateway\u002Fexamples\u002Fecho\u002Fts-example\u002Fclient.ts) and the [instructions](net\u002Fgrpc\u002Fgateway\u002Fexamples\u002Fecho\u002Fts-example) to run.\n\n## Custom Interceptors\n\nCustom interceptors can be implemented and chained, which could be useful for features like auth, retries, etc.\n\nThere are 2 types of interceptors ([interfaces](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc-web\u002Fblob\u002F3cd7e0d43493d4694fed78400e4ad78031d70c09\u002Fpackages\u002Fgrpc-web\u002Findex.d.ts#L55-L65)):\n\n- `UnaryInterceptor` ([doc](https:\u002F\u002Fgrpc.io\u002Fblog\u002Fgrpc-web-interceptor\u002F#stream-interceptor-example), [example](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc-web\u002Fblob\u002Fmaster\u002Fpackages\u002Fgrpc-web\u002Ftest\u002Ftsc-tests\u002Fclient04.ts)) - Intercept Unary RPCs; can only be used with Promise clients.\n- `StreamInterceptor` ([doc](https:\u002F\u002Fgrpc.io\u002Fblog\u002Fgrpc-web-interceptor\u002F#stream-interceptor-example), [example](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc-web\u002Fblob\u002Fmaster\u002Fpackages\u002Fgrpc-web\u002Ftest\u002Ftsc-tests\u002Fclient03.ts)) - More versatile; can be used with regular clients.\n\nFor more details, see [this blog post](https:\u002F\u002Fgrpc.io\u002Fblog\u002Fgrpc-web-interceptor\u002F).\n\n\n## Ecosystem\n\n### Proxy Interoperability\n\nMultiple proxies support the gRPC-web protocol.\n\n1. The current **default proxy** is [Envoy][], which supports gRPC-web out of the box.\n\n\t```sh\n\t$ docker-compose up -d node-server envoy commonjs-client\n\t```\n\n2. You can also try the [gRPC-web Go Proxy][].\n\n\t```sh\n\t$ docker-compose up -d node-server grpcwebproxy binary-client\n\t```\n\n3. Apache [APISIX](https:\u002F\u002Fapisix.apache.org\u002F) has also added gRPC-web support, and more details can be found [here](https:\u002F\u002Fapisix.apache.org\u002Fblog\u002F2022\u002F01\u002F25\u002Fapisix-grpc-web-integration\u002F).\n\n4. [Nginx](https:\u002F\u002Fwww.nginx.com\u002F) has a gRPC-web module ([doc](https:\u002F\u002Fnginx.org\u002Fen\u002Fdocs\u002Fhttp\u002Fngx_http_grpc_module.html), [announcement](https:\u002F\u002Fwww.nginx.com\u002Fblog\u002Fnginx-1-13-10-grpc\u002F))), and seems to work with simple configs, according to user [feedback](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc-web\u002Fdiscussions\u002F1322).\n\n### Server Frameworks with gRPC-Web support\n- [Armeria (JVM)](https:\u002F\u002Farmeria.dev\u002Fdocs\u002Fserver-grpc\u002F#grpc-web)\n- [Tonic (Rust)](https:\u002F\u002Fdocs.rs\u002Ftonic-web\u002Flatest\u002Ftonic_web\u002F)\n\n### Web Frameworks Compatibility\n- **Vite** - See this [demo app](https:\u002F\u002Fgithub.com\u002Fa2not\u002Fvite-grpc-web), as well as this [comment](https:\u002F\u002Fgithub.com\u002Fgrpc\u002Fgrpc-web\u002Fissues\u002F1242#issuecomment-1816249928).\n\n[Envoy]: https:\u002F\u002Fwww.envoyproxy.io\n[gRPC]: https:\u002F\u002Fgrpc.io\n[grpc-web-docs]: https:\u002F\u002Fgrpc.io\u002Fdocs\u002Flanguages\u002Fweb\n[gRPC-web Go Proxy]: https:\u002F\u002Fgithub.com\u002Fimprobable-eng\u002Fgrpc-web\u002Ftree\u002Fmaster\u002Fgo\u002Fgrpcwebproxy\n[Hello World example]: net\u002Fgrpc\u002Fgateway\u002Fexamples\u002Fhelloworld\n","gRPC Web 是一个专为浏览器客户端设计的 gRPC 实现，允许 web 应用通过 HTTP\u002F2 或 HTTP\u002F1.1 与 gRPC 服务通信。它支持一元 RPC 和服务器端流式 RPC（仅在使用 `grpcwebtext` 模式时），但目前不支持客户端流和双向流。该项目基于 JavaScript 开发，依赖 Envoy 作为代理来连接 gRPC 服务，并提供了详细的快速入门指南帮助开发者定义服务、实现简单的 gRPC 服务、配置 Envoy 代理以及生成客户端所需的代码。适用于需要在浏览器环境中调用 gRPC 服务的各种前端应用场景，如构建实时交互性强的 web 应用程序。",2,"2026-06-11 03:30:18","top_topic"]