How to integrate GRPC API in React app?

[alexkoren-dev]

🏷️ Discussion Type

Question

💬 Feature/Topic Area

API

Body

Can anyone teach me how to integrate a gRPC API into a React application, including setting up gRPC-Web, configuring client services, handling requests and responses, and connecting frontend components to backend gRPC endpoints?

[unitech1120]

How to Integrate a gRPC API in a React Application

Integrating a gRPC API into a React application differs from consuming a traditional REST API because browsers cannot communicate directly with standard gRPC services. To bridge this gap, developers typically use gRPC-Web, which enables React applications to communicate with gRPC servers through a proxy such as Envoy.

What is gRPC?

gRPC is a high-performance Remote Procedure Call (RPC) framework developed by Google. It uses HTTP/2 and Protocol Buffers (protobuf) to provide efficient, strongly typed communication between services.

Compared to REST APIs, gRPC offers:

• Faster communication
• Smaller payload sizes
• Automatic code generation
• Better type safety

Typical Architecture

A typical React and gRPC setup consists of:

• React frontend
• gRPC-Web client
• Envoy proxy
• gRPC backend server

The React application sends requests using gRPC-Web, Envoy translates them into standard gRPC requests, and the backend service processes them.

Step 1: Define a Protocol Buffer

The API contract is defined using a .proto file. This file contains service definitions and message structures that both the frontend and backend use.

Example:

• Define a service such as UserService
• Define request and response messages like UserRequest and UserResponse

Step 2: Generate Client Code

Using the Protocol Buffer compiler (protoc) and the gRPC-Web plugin, generate TypeScript or JavaScript client files from the .proto definitions.

These generated files provide:

• Service client classes
• Request and response objects
• Type definitions

Step 3: Configure a gRPC Client

Create a client instance that points to the gRPC-Web endpoint exposed by Envoy.

The client becomes the central object used to communicate with backend services throughout the application.

Step 4: Create an API Service Layer

Instead of calling the generated client directly inside React components, create a service layer that wraps gRPC calls.

Benefits

• Cleaner code
• Easier testing
• Better separation of concerns
• Reusable API functions

Example service methods:

• getUser()
• createUser()
• updateUser()

Step 5: Use the Service Inside React Components

React components can call the API service functions using hooks such as useEffect and useState.

Typical flow:

1. Component loads
2. API request is sent
3. Response data is stored in state
4. UI updates automatically

TypeScript Support

gRPC integrates well with TypeScript because the generated code includes type definitions.

Advantages

• Autocomplete support
• Compile-time error checking
• Better developer experience

Authentication

Authentication tokens such as JWTs can be passed through gRPC metadata.

Common use cases:

• User authentication
• Role-based access control
• Protected API endpoints

Error Handling

gRPC returns structured error codes that can be handled on the frontend.

Common error codes include:

• OK
• Not Found
• Permission Denied
• Unauthenticated
• Service Unavailable

Applications should display meaningful error messages and handle failures gracefully.

React Query Integration

For production applications, integrating gRPC with React Query is highly recommended.

Benefits

• Automatic caching
• Retry mechanisms
• Background refetching
• Loading and error states

This significantly improves application performance and user experience.

Streaming Support

One of gRPC's biggest advantages is streaming.

Supported communication patterns:

• Unary Requests
• Server Streaming
• Client Streaming
• Bidirectional Streaming

In browser environments using gRPC-Web, unary requests and server-streaming are the most commonly supported.

Streaming is useful for:

• Notifications
• Live dashboards
• Chat applications
• Real-time updates

Recommended Project Structure

src/
├── grpc/
│   ├── generated/
│   ├── client/
│   └── services/
├── components/
├── pages/
└── hooks/

Keeping gRPC logic isolated makes the application easier to maintain.

Best Practices

• Use TypeScript for strong typing
• Store .proto files in version control
• Create a dedicated API service layer
• Use environment variables for API endpoints
• Integrate React Query for data management
• Implement proper error handling
• Keep generated files separate from application code

When to Use gRPC

Use gRPC when:

• Building high-performance applications
• Working with microservices
• Requiring strict typing
• Needing real-time streaming
• Developing enterprise-scale systems

Use REST when:

• Building public APIs
• Simplicity is a priority
• Browser compatibility is critical
• Third-party integrations are required

Typical Production Stack

A modern production setup often includes:

• React
• TypeScript
• React Query
• gRPC-Web
• Envoy Proxy
• Node.js, Go, Java, or .NET gRPC backend
• Protocol Buffers

This architecture provides excellent performance, scalability, and maintainability for modern web applications.

[it-mario]

Hey, Alex

Here is a sample code that shows making a simple gRPC client.

`const GRPC_METHODS = Object.values(GRPC_SERVICES).flatMap((service) =>
Object.keys(service.methods)
) as (keyof (typeof GRPC_SERVICES)[keyof typeof GRPC_SERVICES]['methods'])[];

export type GRPCServiceType = keyof typeof GRPC_SERVICES;
export type GRPCMethodType = (typeof GRPC_METHODS)[number];

const header: Interceptor = (next) => async (req) => {
const zhbr = getAccessToken();
if (zhbr !== null) {
req.header.set('Authorization', 'Bearer ' + zhbr);
}

const serviceName = req?.service?.typeName;
const methodName = req?.method?.name;

logger.log([HTTP][REQ][${methodName}], req.url, {
request: req,
});

return await next(req)
.then((res) => {
const newToken = res.header.get('X-New-Access-Token');
if (newToken) {
setAccessToken(newToken);
}
logger.log([HTTP][RES][${methodName}], req.url, {
response: res.message,
});
return res;
})
.catch(async (e) => {
if (e instanceof ConnectError) {
logger.warn('[HTTP][RES][ERROR]', Code[e.code], e.message);
if (e.code === Code.Unauthenticated) {
// Unauthenticated -- Navigate user to login page
removeAccessToken();
store.setIsAuthenticated(false);
window.location.href = BASIC_ROUTES['LOGIN'];
} else {
errorHandler(e, serviceName, methodName); // Handle other errors
}
} else {
// show default error message
errorHandler({ code: -1, message: '' }, serviceName, methodName);
}
throw e;
});
};

const transport = createConnectTransport({
baseUrl: import.meta.env.VITE_APP_GATEWAY_URL as string,
interceptors: [header],
});

export function grpcClient(service: T): Client {
return createClient(service, transport);
}`

[unitech1120]

@it-mario Can you also show me how to use this gRPC client?

[it-mario]

Sure, here it is.

/**

• function to get specific method from grpc service
• @param key The String that specifies the service name and method name
• @returns grpc method
  */
  export const getGrpcMethod = (key: string): ((params: object) => Promise) => {
  const [service, method] = key.split('.');
  return grpcClient(GRPC_SERVICES[service as GRPCServiceType])[method as GRPCMethodType];
  };