flutter_grpc_kit
Build application-friendly gRPC clients for Flutter without exposing generated requests, responses, and stubs throughout the app.
The main abstraction is GrpcServiceClient<TStub>: extend it to wrap a
generated stub, expose methods shaped for your application, transform protobuf
responses, and return consistent Result values. Supporting building blocks
provide shared execution, channels, authentication, and logging:
GrpcServiceClient— base class for generated stub wrappersGrpcExecutor— unary RPC helper with auth token metadata, response transformation, and single-flight token refresh onUNAUTHENTICATEDGrpcChannelFactory/GrpcEndpoint— parse gateway URLs and own a sharedClientChannelGrpcLoggingInterceptor— PrettyDio-style boxed logs in debug
For flutter_alice network inspection, add grpc_alice_interceptor.
Contributions welcome — see CONTRIBUTING.md.
Install
dependencies:
flutter_grpc_kit: ^0.1.0
grpc: ^5.1.0
protobuf: ^6.0.0
Optional Alice inspector:
dependencies:
grpc_alice_interceptor: ^0.1.1
flutter_alice: ^2.0.1
From Git:
dependencies:
flutter_grpc_kit:
git:
url: https://github.com/andreishemetov/flutter_grpc_kit.git
ref: v0.1.0
For local development, use a path dependency to this repo.
Quick start
import 'package:flutter_grpc_kit/flutter_grpc_kit.dart';
final factory = GrpcChannelFactory(gatewayUrl: 'https://grpc.example.com');
final executor = GrpcExecutor(
authHandler: myAuthHandler,
metadata: {'x-app-version': '1.0.0'},
);
final interceptors = [
GrpcLoggingInterceptor(),
];
final greeterClient = GreeterGrpcClient(
channel: factory.channel,
executor: executor,
interceptors: interceptors,
);
final result = await greeterClient.sayHello(
name: 'world',
);
result.fold(
onSuccess: (value) => /* ... */,
onFailure: (error) => /* ... */,
);
Define the application-facing client next to your networking layer:
final class GreeterGrpcClient extends GrpcServiceClient<GreeterClient> {
GreeterGrpcClient({
required super.channel,
required super.executor,
super.interceptors = const [],
super.stub,
}) : super(stubFactory: GreeterClient.new);
Future<Result<String, Exception>> sayHello({required String name}) {
return executor.run(
(options) => stub.sayHello(
HelloRequest(name: name),
options: options,
),
transform: (reply) => reply.message,
);
}
}
Only this class imports the generated request, response, and stub types. The
rest of the application works with sayHello, a String, and Result.
Implement AuthHandler in your app when authentication is required. Shared
headers can be supplied through GrpcExecutor.metadata.
Example app
The example/ app demonstrates a concrete
GreeterGrpcClient and calls the public
hello.HelloService/SayHello API over TLS. From the repo
root:
For a detailed walkthrough with usage examples, read the article on ashemetau.vercel.app or Medium.
cd example
flutter run
Tap SayHello to call https://grpcb.in on port 443. A successful request
with the default name displays Reply: hello world. Calls time out after 10
seconds instead of leaving the UI in a loading state. Use the network icon in
the app bar to inspect recorded calls with Alice.
The Android emulator must have working DNS. If it reports a
Failed host lookup: 'grpcb.in' error, cold-boot the emulator or launch it with
an explicit DNS server:
emulator -avd <your-avd-name> -dns-server 8.8.8.8
To use the optional local server instead, run dart run bin/server.dart from
the example directory and set the app endpoint to:
http://127.0.0.1:50051on iOS Simulator or desktophttp://10.0.2.2:50051on Android Emulator
Development
flutter pub get
flutter test
dart analyze
cd example && flutter pub get && dart analyze && flutter test
Pull requests run the same checks via GitHub Actions. In branch protection, require CI / analyze (or analyze).
AI coding agents
Repository-specific development guidance is available in
AGENTS.md.
A reusable integration workflow for AI coding agents is available in
skills/flutter-grpc-kit. It teaches agents to wrap
generated stubs in application-facing GrpcServiceClient classes, reuse shared
networking infrastructure, preserve authentication behavior, and add focused
tests without exposing generated protobuf types to presentation code.
License
MIT — see LICENSE.
Libraries
- flutter_grpc_kit
- gRPC utilities for Flutter: executor, channels, and logging.