
# 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](../spring-boot-starter-flutter/index.md): 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 a `Future` or a `Stream` too, 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 `build` read;
- 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](beside-change-notifier.md)).

## Setup

```yaml
# 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:

```dart
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:

```dart
// 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

```bash
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 `Watch` is built again, and `save` runs once more.
- `CouponLabel` is not built again for it: its `build` read only the coupon.
- In a debug build, the debug panel has a "State" tab with `Basket` and its members by name.

## What is inside

- [Fields and computed values](fields-and-computed.md): `@Signal` and `@Computed`, where they go, what counts as a change.
- [Collections](collections.md): a `List`, `Set`, `Map` or `Queue` field tells of a change in place.
- [Asynchronous state](async-state.md): a `@Computed` `Future` or `Stream`, `state`, `refresh()`, `reload()`.
- [Effects](effects.md): `@Effect`, `untracked`, one change for a method, `batch`.
- [In widgets](widgets.md): Spring widgets, `Watch`, `AsyncView`.
- [The lifetime of state](lifetime.md): the state ends with its bean.
- [Beside ChangeNotifier](beside-change-notifier.md): when to use which, and Bloc as the third way.
- [What the build checks](build-checks.md): what fails the build, and what does not.
- [The debug tab and the log](debug-tab.md): the State tab, `@Signal(hidden: true)`, the logger.
- [Testing](testing.md): 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.

## See also

- [spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md)
- [State beans](../spring-boot-starter-flutter/state-beans.md)
- [Beans in widgets](../spring-boot-starter-flutter/beans-in-widgets.md)
- [AOP in spring_core_dart](../spring-core-dart/aop/index.md)
- [What a build contains](optimizations.md)
