{"id":23054128,"url":"https://github.com/vertx-howtos/grpc-web-howto","last_synced_at":"2026-04-02T02:07:26.423Z","repository":{"id":267814876,"uuid":"902443408","full_name":"vertx-howtos/grpc-web-howto","owner":"vertx-howtos","description":"Building a gRPC Web service","archived":false,"fork":false,"pushed_at":"2025-05-23T08:03:51.000Z","size":180,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-08-20T10:37:11.222Z","etag":null,"topics":["grpc","grpcweb","howto","vertx"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vertx-howtos.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-12T15:20:32.000Z","updated_at":"2025-05-23T08:03:55.000Z","dependencies_parsed_at":"2025-04-03T04:41:18.650Z","dependency_job_id":"d70d49e3-b9ef-4e48-8b58-42c77acde313","html_url":"https://github.com/vertx-howtos/grpc-web-howto","commit_stats":null,"previous_names":["vertx-howtos/grpc-web-howto"],"tags_count":0,"template":false,"template_full_name":"vertx-howtos/howto-template","purl":"pkg:github/vertx-howtos/grpc-web-howto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fgrpc-web-howto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fgrpc-web-howto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fgrpc-web-howto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fgrpc-web-howto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vertx-howtos","download_url":"https://codeload.github.com/vertx-howtos/grpc-web-howto/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fgrpc-web-howto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31294398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T01:43:37.129Z","status":"online","status_checked_at":"2026-04-02T02:00:08.535Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grpc","grpcweb","howto","vertx"],"created_at":"2024-12-16T00:33:59.040Z","updated_at":"2026-04-02T02:07:26.406Z","avatar_url":"https://github.com/vertx-howtos.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Building a gRPC Web service\n:page-permalink: /\n:page-github: vertx-howtos/grpc-web-howto\n\nifdef::env-github[]\nimage:https://github.com/vertx-howtos/grpc-web-howto/workflows/Publish%20the%20how-to/badge.svg[\"Build Status\",link=\"https://github.com/vertx-howtos/grpc-web-howto/actions?query=workflow%3A%22Publish+the+how-to%22\"]\nendif::env-github[]\n\nThis document will show you how to build a browser/server application with Vert.x and https://github.com/grpc/grpc-web[gRPC Web].\n\n== What you will build\n\nThe application involves a client, the browser, and a Vert.x server:\n\n* the user types a name in a text field and clicks the send button\n* the browser sends the name to the server using the gRPC Web protocol\n* the server replies with a greeting\n* the browser displays the greeting\n\nOn the server side, you will create a Vert.x gRPC server service that:\n\n* implements a gRPC server stub\n* configures an HTTP server replying to both gRPC Web and static file requests\n\nOn the client side, you will create a web page that uses the gRPC Web Javascript client.\n\nimage::run.png[]\n\n== What you need\n\n* A text editor or an IDE\n* Java 17 or higher\n\nYou don't have to install `protoc` or the protoc plugins like vertx-grpc-protoc-plugin2, protobuf-javascript and protoc-gen-grpc-web as they will be managed by a Maven plugin.\n\n== Create the project\n\n=== gRPC service definition\n\nThe gRPC `Greeter` service consists in a single `SayHello` rpc method.\nThe `HelloRequest` message contains the name sent by the client.\nThe `HelloReply` message contains the greeting generated by the server.\n\nifdef::env-github[]\nlink:src/main/proto/service.proto[`service.proto` file]\nendif::env-github[]\nifndef::env-github[]\n[source,protobuf]\n.`service.proto` file\n----\ninclude::src/main/proto/service.proto[]\n----\nendif::env-github[]\n\n=== Code generation\n\nFrom the service definition, several files must be generated:\n\n* Java message and server classes\n* Javascript files\n* gRPC Web specific (Javascript) files.\n\nThe `protoc` invocation is managed with the https://github.com/ascopes/protobuf-maven-plugin[`protobuf-maven-plugin`].\n\nifdef::env-github[]\nlink:pom.xml[Maven POM file]\nendif::env-github[]\nifndef::env-github[]\n[source,xml]\n.Code generation with `protobuf-maven-plugin`\n----\ninclude::pom.xml[tags=\"protobuf-maven-plugin\",indent=0]\n----\n\n\u003c1\u003e We choose to use the `CommonJS` modules generation style instead of closures.\nendif::env-github[]\n\n=== The server side\n\nWe need some dependencies for the project to compile:\n\nifdef::env-github[]\nlink:pom.xml[Maven POM file]\nendif::env-github[]\nifndef::env-github[]\n[source,xml]\n.Project dependencies\n----\ninclude::pom.xml[tags=\"dependencies\",indent=0]\n----\nendif::env-github[]\n\nThe server side code fits in a single `ServerVerticle` class.\n\nFirst, the gRPC server stub implementation.\n\nifdef::env-github[]\nlink:src/main/java/io/vertx/howtos/grpcweb/ServerVerticle.java[Verticle file]\nendif::env-github[]\nifndef::env-github[]\n[source,java]\n.gRPC server stub implementation\n----\ninclude::src/main/java/io/vertx/howtos/grpcweb/ServerVerticle.java[tags=\"grpcServer\",indent=0]\n----\nendif::env-github[]\n\nThere is nothing specific to gRPC Web here.\n\nNOTE: `GrpcServer` enables the gRPC Web protocol support by default.\n\nThen we have to configure a Vert.x Web `Router` to accept both gRPC Web and static file requests.\n\nifdef::env-github[]\nlink:src/main/java/io/vertx/howtos/grpcweb/ServerVerticle.java[Verticle file]\nendif::env-github[]\nifndef::env-github[]\n[source,java]\n.Router and server configuration\n----\ninclude::src/main/java/io/vertx/howtos/grpcweb/ServerVerticle.java[tags=\"routerAndServer\",indent=0]\n----\n\n\u003c1\u003e All requests with `application/grpc-web-text` content type will be handed over to the `grpcServer`.\n\u003c2\u003e All other `GET` requests will be handled by a Vert.x Web `StaticHandler`.\nendif::env-github[]\n\n=== The client side\n\nBefore writing code, we must set up the project to build client side code.\nFor simplicity, we choose to use the https://github.com/mvnpm/esbuild-maven-plugin[`esbuild-maven-plugin`].\nIn a few words, it's a Maven plugin that wraps https://esbuild.github.io/[`esbuild`], a fast bundler for the web.\n\nA couple of dependencies are required, which we grab as Maven dependencies thanks to https://mvnpm.org/[`mvnpm`]:\n\n* https://www.npmjs.com/package/google-protobuf/v/3.21.4[`google-protobuf`]\n* https://www.npmjs.com/package/grpc-web/v/1.5.0[`grpc-web`]\n\nifdef::env-github[]\nlink:pom.xml[Maven POM file]\nendif::env-github[]\nifndef::env-github[]\n[source,xml]\n.Client code build with `esbuild-maven-plugin`\n----\ninclude::pom.xml[tags=\"esbuild-maven-plugin\",indent=0]\n----\n\n\u003c1\u003e `webroot` is the default base directory from where the Vert.x Web `StaticHandler` serves static files.\nendif::env-github[]\n\nThe user interface code fits in a single `index.html` file.\n\nifdef::env-github[]\nlink:src/main/resources/webroot/index.html[HTML file]\nendif::env-github[]\nifndef::env-github[]\n[source,html]\n.User interface\n----\ninclude::src/main/resources/webroot/index.html[indent=0]\n----\n\n\u003c1\u003e Import the `sayHello` function from our Javascript module (see below).\n\u003c2\u003e Make the `sayHello` function global.\nendif::env-github[]\n\nLast but not least, let's implement the `sayHello` function:\n\nifdef::env-github[]\nlink:src/main/web/index.js[Application JS file]\nendif::env-github[]\nifndef::env-github[]\n[source,javascript]\n.Using the gRPC Web client\n----\ninclude::src/main/web/index.js[indent=0]\n----\n\n\u003c1\u003e Import the `HelloRequest` object from the Javascript generated file.\n\u003c2\u003e Import the `GreeterClient` object from gRPC Web (Javascript) generated file.\n\u003c3\u003e Configure the client to send requests to the web server.\nendif::env-github[]\n\n== Running the application\n\nYou can run the application with Maven:\n\n[source,shell]\n----\n./mvnw compile exec:java\n----\n\nYou should see:\n\n----\nServer started, browse to http://localhost:8080\n----\n\nYou can now browse to http://localhost:8080 and follow the instructions.\n\nUse the dev tools of your browser to inspect the gRPC Web traffic.\n\nimage::devtools.png[]\n\n== Summary\n\nThis document covered:\n\n. implementing a Vert.x web server that replies to both static file and gRPC Web requests,\n. creating a web page that uses the gRPC Web client.\n\n== See also\n\n* https://vertx.io/docs/vertx-grpc/java/[Vert.x gRPC documentation]\n* https://github.com/grpc/grpc-web[gRPC Web project]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvertx-howtos%2Fgrpc-web-howto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvertx-howtos%2Fgrpc-web-howto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvertx-howtos%2Fgrpc-web-howto/lists"}