Migrating from signals.dart v6 to v7

This guide provides comprehensive instructions for migrating applications and packages using signals.dart from version 6.x to 7.0.0.

Related Documentation & Items

1. Unified Options Classes (Named Parameter Pattern)

In v6, signals, computed, effects, and async signals accepted individual parameters like autoDispose, debugLabel, lazy, etc. In v7, all parameters have been unified under a single, cohesive options class parameter.

A. General Signals

• Before (v6):

``dart final count = signal(0, autoDispose: true, debugLabel: 'counter'); ``

• After (v7):

``dart final count = signal(0, options: SignalOptions(autoDispose: true, name: 'counter')); ``

B. Computed Signals

• Before (v6):

``dart final double = computed(() => count.value * 2, autoDispose: true, debugLabel: 'double'); ``

• After (v7):

``dart final double = computed(() => count.value * 2, options: ComputedOptions(autoDispose: true, name: 'double')); ``

C. Collections Signals (listSignal, setSignal, mapSignal, etc.)

All collections now accept unified options objects corresponding to their types (e.g. ListSignalOptions, SetSignalOptions, MapSignalOptions, IterableSignalOptions, QueueSignalOptions).

• Before (v6):

``dart final list = listSignal([1, 2], autoDispose: true); ``

• After (v7):

``dart final list = listSignal([1, 2], options: ListSignalOptions(autoDispose: true)); ``

2. Async Signals Refactoring

All async creators (futureSignal, streamSignal, asyncSignal, computedFrom, computedAsync) now accept only the primary value/callback parameter followed by a named options parameter (AsyncSignalOptions). All other parameters have been marked @Deprecated.

• Before (v6):

``dart final s = futureSignal(() => fetch(), lazy: false, initialValue: 0); ``

• After (v7):

``dart final s = futureSignal(() => fetch(), options: AsyncSignalOptions(lazy: false, initialValue: 0)); ``

3. Flutter Integration Upgrades

A. Deprecation of SignalsMixin

SignalsMixin is deprecated to prevent state overhead. Use localized widgets or builders instead.

• Migration:

- Replace State with SignalsMixin with a stateless SignalWidget or a stateful SignalStatefulWidget. - Alternatively, use localized SignalBuilder widgets to wrap only the widgets that depend on signal updates.

B. SignalBuilder Named builder Parameter

The SignalBuilder widget now uses a required named parameter builder instead of a positional argument.

• Before (v6):

``dart SignalBuilder( (context, value) => Text('$value'), ) ``

• After (v7):

``dart SignalBuilder( builder: (context, value) => Text('$value'), ) ``

C. Side Effects with SignalEffect / SignalListener

If you were executing side effects inside builds or mixins, migrate them to the localized SignalEffect (or alias SignalListener) widget which manages mounting, didUpdateWidget, and unmounting teardown lifecycle hooks safely.

SignalEffect(
  callback: (context) {
    if (error.value != null) {
      ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(error.value!)));
    }
  },
  child: MyWidget(),
)

4. Writable Computed Signals (linkedSignal)

If you had custom logic synchronizing external updates back to a computed signal, migrate them to the native linkedSignal or LinkedSignalOptions.

final original = signal('Alice');
final display = linkedSignal(() => original.value);

print(display.value); // 'Alice'
display.value = 'Bob'; // Override manual write
original.value = 'Charlie'; // Source changes -> resets display to 'Charlie'

5. Automated Refactoring via signals_lint

To make migrating from v6 to v7 completely effortless, the signals_lint tool analyzes your code and surfaces instant, automated quick-fixes/assists under your IDE's action menu (Alt+Enter or Cmd+.):

• Strips legacy with SignalsMixin and replaces the widget with a high-performance SignalStatefulWidget automatically.
• Converts positional Watch and Watch.builder instances into unified SignalBuilder components.
• Promotes standard StatelessWidget and StatefulWidget widgets to reactive SignalWidget and SignalStatefulWidget widgets on command.
• Quickly wraps any widget expression in a surgically targeted SignalBuilder.