trpc_flutter
Flutter integration for trpc_dart. Bridges cache-backed tRPC queries directly to Flutter's native ValueListenable interface for declarative UI rendering.
Part of the rpc-dart monorepo.
Why trpc_flutter?
- Native Flutter primitives: Bridges query caches to
ValueListenable<RpcAsyncState<T>>without third-party state management dependencies. - Works with any UI pattern: Drop straight into
ValueListenableBuilder,ListenableBuilder, Riverpod, BLoC, Provider, or vanillasetState. - Automatic cache synchronization: UI widgets rebuild when data loads, errors occur, or cache invalidations trigger background refetches.
- Generated procedure ergonomics: Call
.listenable(input)directly on generated procedure instances (api.user.getById.listenable(input)).
Installation
Add trpc_flutter and trpc_dart to your pubspec.yaml:
dependencies:
flutter:
sdk: flutter
trpc_dart: ^0.2.0
trpc_flutter: ^0.2.0
Then run:
flutter pub get
Quickstart
1. Configure the client and root API
import 'package:flutter/material.dart';
import 'package:trpc_dart/trpc_dart.dart';
import 'package:trpc_flutter/trpc_flutter.dart';
import 'api/api.dart'; // generated bindings
final client = RpcClient(
endpoint: Uri.parse('https://api.example.com/trpc'),
transformer: RpcTransformer.superjson,
links: [
HttpBatchLink(endpoint: Uri.parse('https://api.example.com/trpc')),
],
);
final api = Api(client);
2. Render with ValueListenableBuilder
class UserProfileWidget extends StatelessWidget {
const UserProfileWidget({super.key, required this.userId});
final String userId;
@override
Widget build(BuildContext context) {
// .listenable(input) returns a ValueListenable<RpcAsyncState<User>>
return ValueListenableBuilder<RpcAsyncState<User>>(
valueListenable: api.user.getById.listenable(UserGetByIdInput(id: userId)),
builder: (context, state, _) => switch (state) {
RpcAsyncLoading() => const Center(child: CircularProgressIndicator()),
RpcAsyncError(:final error) => Center(child: Text('Error: $error')),
RpcAsyncData(:final data) => Text('Welcome, ${data.name}!'),
},
);
}
}
When mutations call client.cache.invalidate(...), any active listenable referencing the affected keys refetches and updates the widget automatically.
State Management Integration
Riverpod
Wrap the listenable in a ValueListenableProvider:
final userProfileProvider = Provider.family<ValueListenable<RpcAsyncState<User>>, String>(
(ref, id) => api.user.getById.listenable(UserGetByIdInput(id: id)),
);
BLoC / Cubit
Listen to the query ref's stream in your Cubit:
class UserCubit extends Cubit<RpcAsyncState<User>> {
UserCubit(String userId) : super(const RpcAsyncLoading()) {
_subscription = api.user.getById
.watch(UserGetByIdInput(id: userId))
.stream
.listen(emit);
}
late final StreamSubscription<RpcAsyncState<User>> _subscription;
@override
Future<void> close() {
_subscription.cancel();
return super.close();
}
}
Provider
Expose ValueListenable with ValueListenableProvider:
ValueListenableProvider<RpcAsyncState<User>>.value(
value: api.user.getById.listenable(UserGetByIdInput(id: userId)),
child: const UserView(),
);
Links
- Documentation
- Dart Runtime (trpc_dart)
- CLI Generator (rpc-dart)
- Flutter Integration Guides
- GitHub Repository
- Issue Tracker
License
MIT © Aditya Jandu
Live subscriptions
RpcSubscriptionController binds generated .subscribe() streams to a
ValueListenable<RpcSubscriptionState<T>>, surfaces a reconnecting status
across drops, and can auto-invalidate query-cache prefixes as events arrive:
final controller = RpcSubscriptionController<String>(
streamFactory: ({lastEventId, onReconnect}) => api.streams.onActivityFeed
.subscribe(
StreamsOnActivityFeedInput(
lastEventId: lastEventId == null ? null : RpcPresent(lastEventId),
),
options: RpcSubscriptionOptions(
lastEventId: lastEventId,
onReconnect: onReconnect,
),
)
.map((event) => event.message),
keepHistoryCount: 20,
queryCache: client.cache,
invalidatePrefixesOnData: [['streams', 'onActivityFeed']],
)..start();
Libraries
- trpc_flutter
- Flutter integration for trpc_dart: provides a ValueListenable bridge over cache-backed queries for ValueListenableBuilder, Riverpod, BLoC, and Provider.