Skip to content

Commit cfcc5e3

Browse files
authored
Improve plugin install instructions (#1419)
1 parent a639b4c commit cfcc5e3

File tree

2 files changed

+64
-30
lines changed

2 files changed

+64
-30
lines changed

README.md

Lines changed: 56 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -53,35 +53,78 @@ The gRPC-web runtime library is available at `npm`:
5353
$ npm i grpc-web
5454
```
5555

56-
## Code Generator Plugin
56+
## Code Generator Plugins
57+
58+
### (Prerequisite) 1. Protobuf (`protoc`)
59+
60+
If you don't already have [`protoc`](https://github.com/protocolbuffers/protobuf)
61+
installed, download it first from [here](https://github.com/protocolbuffers/protobuf/releases) and install it on your PATH.
62+
63+
Or run:
64+
65+
```sh
66+
brew install protobuf
67+
```
68+
69+
### (Prerequisite) 2. Protobuf-javascript (`protoc-gen-js`)
70+
71+
If you don't have [`protoc-gen-js`](https://github.com/protocolbuffers/protobuf-javascript) installed, download it from [protocolbuffers/protobuf-javascript](https://github.com/protocolbuffers/protobuf-javascript/releases) and install it on your PATH.
72+
73+
Or, use the [third-party](https://www.npmjs.com/package/protoc-gen-js) NPM installer:
74+
75+
```
76+
npm install -g protoc-gen-js
77+
```
78+
79+
### 3. Install gRPC-Web Code Generator
5780

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

61-
If you don't already have `protoc` installed, you will have to download it
62-
first from [here](https://github.com/protocolbuffers/protobuf-javascript/releases).
84+
Make sure all executables are discoverable from your PATH.
6385

64-
> **NOTE:** Javascript output is no longer supported by `protocolbuffers/protobuf` package as it previously did. Please use the releases from [protocolbuffers/protobuf-javascript](https://github.com/protocolbuffers/protobuf-javascript/releases) instead.
86+
For example, on MacOS, you can do:
6587

66-
Make sure they are both executable and are discoverable from your PATH.
88+
```sh
89+
sudo mv protoc-gen-grpc-web-1.5.0-darwin-aarch64 \
90+
/usr/local/bin/protoc-gen-grpc-web
91+
92+
chmod +x /usr/local/bin/protoc-gen-grpc-web
93+
```
6794

68-
For example, in MacOS, you can do:
95+
### (Optional) 4. Verify Installations
96+
97+
You can optionally verify the plugins works follwoing our [Hello world example](https://github.com/grpc/grpc-web/tree/master/net/grpc/gateway/examples/helloworld#generating-stubs):
98+
99+
```sh
100+
cd net/grpc/gateway/examples/helloworld
69101

102+
protoc -I=. helloworld.proto \
103+
--js_out=import_style=commonjs:. \
104+
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:.
70105
```
71-
$ sudo mv ~/Downloads/protoc-gen-grpc-web-1.5.0-darwin-x86_64 \
72-
/usr/local/bin/protoc-gen-grpc-web
73-
$ chmod +x /usr/local/bin/protoc-gen-grpc-web
106+
107+
After the command runs successfully, you should now see two new files generated
108+
in the current directory. By running:
109+
74110
```
111+
ls -1 *_pb.js
112+
```
113+
114+
Installation is successful if you see the following 2 files:
115+
116+
- `helloworld_pb.js` # Generated by `protoc-gen-js` plugin
117+
- `helloworld_grpc_web_pb.js` - Generated by gRPC-Web plugin
75118

76119
## Client Configuration Options
77120

78121
Typically, you will run the following command to generate the proto messages
79122
and the service client stub from your `.proto` definitions:
80123

81124
```sh
82-
$ protoc -I=$DIR echo.proto \
83-
--js_out=import_style=commonjs:$OUT_DIR \
84-
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR
125+
protoc -I=$DIR echo.proto \
126+
--js_out=import_style=commonjs:$OUT_DIR \
127+
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR
85128
```
86129

87130
You can then use Browserify, Webpack, Closure Compiler, etc. to resolve imports
@@ -255,7 +298,7 @@ For example, this is the command you should use to generate TypeScript code
255298
using the binary wire format
256299

257300
```sh
258-
$ protoc -I=$DIR echo.proto \
301+
protoc -I=$DIR echo.proto \
259302
--js_out=import_style=commonjs,binary:$OUT_DIR \
260303
--grpc-web_out=import_style=typescript,mode=grpcweb:$OUT_DIR
261304
```

net/grpc/gateway/examples/helloworld/README.md

Lines changed: 8 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -245,30 +245,21 @@ And that's it! We have all the code ready. Let's run the example!
245245

246246
## Generate Protobuf Messages and Client Service Stub
247247

248+
### Install Plugins
249+
248250
To generate the protobuf messages and client service stub class from your
249251
`.proto` definitions, we need:
250252
- the `protoc` binary, _and_
253+
- the `protoc-gen-js` binary, _and_
251254
- the `protoc-gen-grpc-web` plugin.
252255

253-
> You can download the `protoc-gen-grpc-web` protoc plugin from our
254-
> [release](https://github.com/grpc/grpc-web/releases) page.
255-
>
256-
> If you don't already have `protoc` installed, you will have to download it
257-
> first from [here](https://github.com/protocolbuffers/protobuf/releases).
258-
>
259-
> Make sure they are both executable and are discoverable from your PATH.
260-
>
261-
> For example, in MacOS, you can do:
262-
>
263-
> ```sh
264-
> $ sudo mv ~/Downloads/protoc-gen-grpc-web-1.5.0-darwin-x86_64 \
265-
> /usr/local/bin/protoc-gen-grpc-web
266-
> $ sudo chmod +x /usr/local/bin/protoc-gen-grpc-web
267-
> ```
256+
Follow the instructions [here](https://github.com/grpc/grpc-web?tab=readme-ov-file#code-generator-plugins)
257+
if you don't have them installed already.
268258

259+
### Generating stubs
269260

270-
When you have both `protoc` and `protoc-gen-grpc-web` installed, you can now
271-
run this command:
261+
When you have both `protoc`, `protoc-gen-js`, and `protoc-gen-grpc-web`
262+
installed, you can now run this command:
272263

273264
```sh
274265
$ protoc -I=. helloworld.proto \

0 commit comments

Comments
 (0)