Skip to content

Commit

Permalink
docs(subscriber): add a grpc-web app example (#526)
Browse files Browse the repository at this point in the history
## Description

This pull request adds a real web example for the `grpc-web` feature. It
shows how to connect the `console-subscriber` server with a grpc-web
client in the browser.

I also added a GitHub Actions to make sure we keep updating this example
in the future.

## Explanation of Changes

1. It uses vite and react as the basic framework.
2. It uses `connect-es` as the grpc-web client to connect the server.
3. It will spawn an async task to watch the update stream and log the
   update in the browser's console.
  • Loading branch information
Rustin170506 authored Feb 23, 2024
1 parent 4150253 commit 4af30f2
Show file tree
Hide file tree
Showing 30 changed files with 6,972 additions and 1 deletion.
3 changes: 2 additions & 1 deletion .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
* @tokio-rs/console
* @tokio-rs/console
/console-subscriber/examples/grpc_web @hi-rustin
31 changes: 31 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -101,3 +101,34 @@ jobs:

- name: Run cargo clippy
run: cargo clippy -- -D warnings

grpc_web:
name: gRPC-web Example
runs-on: ubuntu-latest
defaults:
run:
working-directory: console-subscriber/examples/grpc_web/app
steps:
- name: Checkout sources
uses: actions/checkout@v4

- name: Use Node.js
uses: actions/setup-node@v4

- name: Install dependencies
run: npm install

- name: Lint
run: npm run lint

- name: Format
run: npm run fmt

- name: Generate
run: npm run gen

- name: Check no changes
run: git diff --exit-code

- name: Build
run: npm run build
50 changes: 50 additions & 0 deletions console-subscriber/examples/grpc_web/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# gRPC-web Example

This app provides an example of using the gRPC-web library to facilitate communication between a web browser and a gRPC server.

## Prerequisites

Ensure you have the following installed on your system:

- [Node.js](https://nodejs.org/en/download/) (version 20.10.0 or higher)
- [npm](https://www.npmjs.com/get-npm) (version 10.2.3 or higher)

## Getting Started

Follow these steps to get the application up and running:

1. **Install Dependencies:** Navigate to the `console-subscriber/examples/grpc_web/app` directory and install all necessary dependencies:

```sh
npm install
```

2. **Start the gRPC-web Server:** In the console-subscriber directory, start the server:

```sh
cargo run --example grpc_web --features grpc-web
```

3. **Start the Web Application:** In the `console-subscriber/examples/grpc_web/app` directory, start the web application:

```sh
npm run dev
```

4. **View the Application:** Open a web browser and navigate to `http://localhost:5173`. You can view the output in the developer console.

## Understanding the Code

This example leverages the [connect-es] library to enable communication with the gRPC server from a web browser. The client code can be found in the `console-subscriber/examples/grpc_web/app/src/app.tsx` file.

The [buf] tool is used to generate the gRPC code. You can generate the code using the following command:

```sh
npm run gen
```

For more information about the connect-es library, refer to the [connect-es documentation].

[connect-es]: https://github.com/connectrpc/connect-es
[buf]: https://buf.build/
[connect-es documentation]: https://connectrpc.com/docs/web/getting-started
18 changes: 18 additions & 0 deletions console-subscriber/examples/grpc_web/app/.eslintrc.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
module.exports = {
root: true,
env: { browser: true, es2020: true },
extends: [
"eslint:recommended",
"plugin:@typescript-eslint/recommended",
"plugin:react-hooks/recommended",
],
ignorePatterns: ["dist", ".eslintrc.cjs"],
parser: "@typescript-eslint/parser",
plugins: ["react-refresh"],
rules: {
"react-refresh/only-export-components": [
"warn",
{ allowConstantExport: true },
],
},
};
24 changes: 24 additions & 0 deletions console-subscriber/examples/grpc_web/app/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*

node_modules
dist
dist-ssr
*.local

# Editor directories and files
.vscode/*
!.vscode/extensions.json
.idea
.DS_Store
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?
1 change: 1 addition & 0 deletions console-subscriber/examples/grpc_web/app/.prettierignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
src/gen/**/*
1 change: 1 addition & 0 deletions console-subscriber/examples/grpc_web/app/README.md
8 changes: 8 additions & 0 deletions console-subscriber/examples/grpc_web/app/buf.gen.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
version: v1
plugins:
- plugin: es
opt: target=ts
out: src/gen
- plugin: connect-es
opt: target=ts
out: src/gen
12 changes: 12 additions & 0 deletions console-subscriber/examples/grpc_web/app/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>gRPC-Web Example</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
Loading

0 comments on commit 4af30f2

Please sign in to comment.