trpc_flutter

pub package pub points license GitHub CI

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 vanilla setState.
  • 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.3.0
  trpc_flutter: ^0.3.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(),
);


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.