Migration page from "old" notifiers to "new" notifiers

website/docs/from_provider/quickstart.mdx

@@ -37,20 +37,21 @@ final myNotifierProvider = ChangeNotifierProvider<MyNotifier>((ref) {
 });
 ```
 
-As you can see Riverpod exposes a [ChangeNotifierProvider] class,
+As you can see, Riverpod exposes a [ChangeNotifierProvider] class,
 which is there precisely to support migrations from pkg:Provider.
 
 Keep in mind that this provider is not recommended when writing new code,
 and it is not the best way to use Riverpod, but it's a gentle and very easy way to start your migration.
 
 :::tip
 There is no rush to *immediately* try to change your `ChangeNotifier`s into the more modern [Riverpod's providers].
-Some requite a bit of a paradigm shift, so it may be difficult to do initially.  
+Some requite a bit of [work], so it may be difficult to do in one take.  
 
 Take your time, as it is important to get yourself familiar with Riverpod first;
 you'll quickly find out that *almost* all Providers from pkg:provider have a strict equivalent in pkg:riverpod.
 :::
 
+
 ## Starts with *leaves*
 
 Start with Providers that do not depend on anything else, i.e. start with the *leaves* in your dependency tree.  
@@ -120,6 +121,10 @@ final myNotifierProvider = NotifierProvider<MyNotifier, int>(MyNotifier.new);
 
 This operation might take some time and might lead to some errors, so don't rush doing this all at once.
 
+Please follow [this migration guide] to migrate from `ChangeNotifier` to the more modern 
+`Notifier` and `AsyncNotifier`, one step at a time.
+
+
 ## Migrating `ProxyProvider`s
 Within pkg:Provider, `ProxyProvider` is used to combine values from other Providers;
 its build depends on the value of other providers, reactively.
@@ -204,4 +209,6 @@ Following this guide, you *can* migrate towards codegen as a further step forwar
 [are composable by default]: /docs/from_provider/motivation#combining-providers-is-hard-and-error-prone
 [as mentioned above]: /docs/from_provider/quickstart#start-with-changenotifierprovider
 [Riverpod's `Consumer` APIs]: /docs/concepts/reading
-[lazy by default]: /docs/concepts/provider_lifecycles
+[lazy by default]: /docs/concepts/provider_lifecycles
+[work]: /docs/from_provider/quickstart#migrate-one-provider-at-a-time
+[this migration guide]: /docs/migration/1.0.0_to_2.0.0#migrating-from-statenotifier

website/docs/migration/add_listener/add_listener.dart

@@ -0,0 +1,16 @@
+// ignore_for_file: avoid_print
+
+import 'package:flutter/material.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+part 'add_listener.g.dart';
+
+/* SNIPPET START */
+@riverpod
+class MyNotifier extends _$MyNotifier {
+  @override
+  int build() {
+    ref.listenSelf((_, next) => debugPrint('$next'));
+    return 0;
+  }
+}

website/docs/migration/add_listener/index.tsx

@@ -0,0 +1,9 @@
+import raw from "!!raw-loader!./raw.dart";
+import codegen from "!!raw-loader!./add_listener.dart";
+
+export default {
+  raw,
+  hooks: raw,
+  codegen,
+  hooksCodegen: codegen,
+};

website/docs/migration/add_listener/raw.dart

@@ -0,0 +1,15 @@
+// ignore_for_file: avoid_print
+
+import 'package:flutter/material.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+/* SNIPPET START */
+class MyNotifier extends Notifier<int> {
+  @override
+  int build() {
+    ref.listenSelf((_, next) => debugPrint('$next'));
+    return 0;
+  }
+}
+
+final myNotifierProvider = NotifierProvider<MyNotifier, int>(MyNotifier.new);

website/docs/migration/async_notifier/async_notifier.dart

@@ -0,0 +1,19 @@
+// ignore_for_file: avoid_print
+
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+part 'async_notifier.g.dart';
+
+class Todo {}
+
+/* SNIPPET START */
+@riverpod
+class AsyncTodosNotifier extends _$AsyncTodosNotifier {
+  @override
+  FutureOr<List<Todo>> build() {
+    // mock of a network request
+    return Future.delayed(const Duration(seconds: 1), () => []);
+  }
+
+  // ...
+}

website/docs/migration/async_notifier/index.tsx

@@ -0,0 +1,9 @@
+import raw from "!!raw-loader!./raw.dart";
+import codegen from "!!raw-loader!./async_notifier.dart";
+
+export default {
+  raw,
+  hooks: raw,
+  codegen,
+  hooksCodegen: codegen,
+};

website/docs/migration/async_notifier/raw.dart

@@ -0,0 +1,20 @@
+// ignore_for_file: avoid_print
+
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+class Todo {}
+
+/* SNIPPET START */
+class AsyncTodosNotifier extends AsyncNotifier<List<Todo>> {
+  @override
+  FutureOr<List<Todo>> build() {
+    // mock of a network request
+    return Future.delayed(const Duration(seconds: 1), () => []);
+  }
+
+  // ...
+}
+
+final asyncTodosNotifier = AsyncNotifierProvider<AsyncTodosNotifier, List<Todo>>(
+  AsyncTodosNotifier.new,
+);

website/docs/migration/build_init/build_init.dart

@@ -0,0 +1,21 @@
+// ignore_for_file: avoid_print
+
+import 'dart:math';
+
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+import '../utils.dart';
+
+part 'build_init.g.dart';
+
+/* SNIPPET START */
+@riverpod
+class WellNotifier extends _$WellNotifier {
+  @override
+  int build() {
+    final availableToDrink = ref.watch(availableWater);
+    return availableToDrink;
+  }
+
+  void drink(int liters) => state = min(state - liters, 0);
+}

website/docs/migration/build_init/index.tsx

@@ -0,0 +1,9 @@
+import raw from "!!raw-loader!./raw.dart";
+import codegen from "!!raw-loader!./build_init.dart";
+
+export default {
+  raw,
+  hooks: raw,
+  codegen,
+  hooksCodegen: codegen,
+};

website/docs/migration/build_init/raw.dart

@@ -0,0 +1,21 @@
+// ignore_for_file: avoid_print
+
+import 'dart:math';
+
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+import '../utils.dart';
+
+/* SNIPPET START */
+class WellNotifier extends Notifier<int> {
+  @override
+  int build() {
+    final availableToDrink = ref.watch(availableWater);
+    return availableToDrink;
+  }
+
+  void drink(int liters) => state = min(state - liters, 0);
+}
+
+final wellNotifierProvider = NotifierProvider<WellNotifier, int>(WellNotifier.new);

website/docs/migration/family_and_dispose/family_and_dispose.dart

@@ -0,0 +1,26 @@
+import 'dart:math';
+
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+import '../utils.dart';
+
+part 'family_and_dispose.g.dart';
+
+/* SNIPPET START */
+@riverpod
+class BugsEncounteredNotifier extends _$BugsEncounteredNotifier {
+  late String _id;
+  @override
+  FutureOr<int> build(String featureId) {
+    _id = featureId;
+    return 99;
+  }
+
+  Future<void> fix(int amount) async {
+    state = await AsyncValue.guard(() async {
+      final old = state.requireValue;
+      final result = await ref.read(taskTrackerProvider).fix(id: _id, fixed: amount);
+      return max(old - result, 0);
+    });
+  }
+}