spring_boot_starter_flutter_signals
spring_boot_starter_flutter_signals puts reactive state into the beans of a Flutter app built on spring_boot_starter_flutter: three annotations on a component, and plain fields.
@Signal()on a field: what read it is told when it is assigned.@Computed()on a getter: a value kept until what it read changes; from aFutureor aStreamtoo, with its state.@Effect()on a method: run again when what it read changes.
Why
A bean with several fields that change apart from each other has two usual answers: one notification for the whole bean, which rebuilds every widget that listens, or a wrapper type around every field with a .value on every read. Here the fields stay plain fields. The bean's generated proxy follows the reads and the assignments, so:
- there are no wrapper types and no
.value; - a widget is built again only for the fields its
buildread; - a value made from others is computed once and kept;
- a request is made again when what it depends on changes.
The starter is built on the third-party package signals_core. It re-exports only batch and untracked from it. It stands beside ChangeNotifier, not instead of it: @ChangeNotifierComponent and @NotifyListeners stay as they are (see Beside ChangeNotifier).
Setup
# pubspec.yaml
environment:
sdk: ^3.14.0
flutter: '>=3.50.0'
dependencies:
flutter:
sdk: flutter
spring_boot_starter_flutter_signals: ^0.9.0
dev_dependencies:
build_runner: ^2.17.0
spring_core_dart_generator: ^0.9.0
The starter brings and re-exports spring_boot_starter_flutter; an app lists this package instead. One import is enough:
import 'package:spring_boot_starter_flutter_signals/spring_boot_starter_flutter_signals.dart';
It needs Flutter 3.50 or later (Dart 3.14). The generator writes the proxies: run dart run build_runner build after adding or removing an annotation.
Example
A basket whose total follows its items and coupon, saved by an effect:
// lib/main.dart
import 'package:flutter/widgets.dart';
import 'package:spring_boot_starter_flutter_signals/spring_boot_starter_flutter_signals.dart';
import 'spring_gen/main.spring.dart';
class Book {
const Book(this.title, this.price);
final String title;
final double price;
}
@Service()
class BasketStorage {
final List<int> saved = [];
void write(int count) => saved.add(count);
}
@Component()
class Basket {
Basket(this.storage); // ordinary injection
final BasketStorage storage;
@Signal()
List<Book> items = [];
@Signal()
String? coupon;
@Computed() // kept until items or coupon changes
double get total =>
items.fold(0.0, (sum, book) => sum + book.price) *
(coupon == null ? 1 : 0.9);
@Effect() // runs again whenever items changes
void save() => storage.write(items.length);
void add(Book book) => items.add(book);
void apply(String code) => coupon = code;
}
// A Spring widget follows its own build: built again when the coupon
// changes, and for nothing else of the basket.
class CouponLabel extends SpringStatelessWidget<(Basket,)> {
const CouponLabel({super.key});
@override
Widget build(BuildContext context) {
final (basket,) = beans;
return Text('Coupon: ${basket.coupon ?? 'none'}');
}
}
class Shop extends StatelessWidget {
const Shop({super.key});
@override
Widget build(BuildContext context) {
final basket = context.bean<Basket>();
return Column(
children: [
GestureDetector(
onTap: () => basket.add(const Book('Dune', 10)),
child: const Text('Add Dune'),
),
// Rebuilt when the total changes, not for anything else.
Watch((context) => Text('Total: ${basket.total}')),
const CouponLabel(),
],
);
}
}
@SpringBootApplication()
void main() => runApp(
SpringApplicationWidget(
application: () => springApplication,
home: const Shop(),
),
);
A component is a singleton unless it says otherwise, so this is the app's state, reached from anywhere by injection or from a widget's context.
Running it
dart run build_runner build # writes the proxies of Basket
flutter run
- A tap on "Add Dune" changes the list in place. The total is computed again, the
Watchis built again, andsaveruns once more. CouponLabelis not built again for it: itsbuildread only the coupon.- In a debug build, the debug panel has a "State" tab with
Basketand its members by name.
What is inside
- Fields and computed values:
@Signaland@Computed, where they go, what counts as a change. - Collections: a
List,Set,MaporQueuefield tells of a change in place. - Asynchronous state: a
@ComputedFutureorStream,state,refresh(),reload(). - Effects:
@Effect,untracked, one change for a method,batch. - In widgets: Spring widgets,
Watch,AsyncView. - The lifetime of state: the state ends with its bean.
- Beside ChangeNotifier: when to use which, and Bloc as the third way.
- What the build checks: what fails the build, and what does not.
- The debug tab and the log: the State tab,
@Signal(hidden: true), the logger. - Testing: the state in tests.
Things to know
- The bean's own calls are followed, and only followed. A bean with such members is proxied by a subclass that sees the calls the bean makes on itself, so a field read or assigned inside a method is followed. Other advice on the bean (
@Transactional,@PreAuthorize,@Cacheable) skips those calls, as in any bean and as in Spring: it runs for a call from outside. - A field nobody read is not followed yet: it is mirrored when first read, from the field itself.
- Equal is unchanged. Assigning a value equal to the one there tells nobody.
- An effect runs at once when what it read is assigned (at the end of the method that assigned it), not in a later frame.
- Not built by the starter: state kept between runs, a history with undo, the state of a running action ("saving..."), server data as a cache with invalidation.
In Spring (Java)
Spring has no counterpart. The shape is Spring's: annotations on the members of a component, and advice around them run by the bean's proxy, as @Transactional and @Cacheable are. One thing differs from Spring: a bean with such members has the calls it makes on itself advised too.