Riverpod

Flutter state management with Riverpod - declarative, type-safe, and code-generated providers. Use when building Flutter apps that need reactive state manage...

Security Scan

The skill is an instruction-only Riverpod guide for Flutter; its requirements and instructions align with that purpose and it does not request credentials, installs, or make unexpected system demands.

Purpose & Capability

The name/description match the SKILL.md and BEST_PRACTICES.md content: Flutter Riverpod patterns, providers, and build_runner usage. It requests no unrelated binaries, environment variables, or config paths.

Instruction Scope

Runtime instructions are documentation and code snippets for using Riverpod in a Flutter project (including running 'flutter pub run build_runner ...'). There are no steps to read unrelated system files, exfiltrate data, or post to unexpected endpoints. Example code references network clients (e.g., Dio) but only as typical sample usage.

Install Mechanism

No install spec and no code files — this is instruction-only documentation. Nothing will be downloaded or written by an installer.

Credentials

The skill declares no required environment variables, credentials, or config paths. Sample snippets mention APIs/clients that a developer would provide in their own project; the skill itself does not request secrets.

Persistence & Privilege

'always' is false and model invocation is normal. The skill does not request persistent system presence or modify other skills/configuration.

Assessment

This skill is documentation-only and appears coherent with its stated purpose. Before using: (1) run the shown build_runner commands only inside a trusted Flutter project (they will modify generated files), (2) review any example network calls (Dio/api) to ensure you supply your own API endpoints and keys rather than copying credentials, and (3) verify Riverpod and Flutter version compatibility with your project. No credentials or installs are requested by the skill itself.

Riverpod State Management

Riverpod is a declarative, type-safe state management solution for Flutter. It uses code generation for boilerplate reduction.

Core Concepts

1. Declarative State with @riverpod

Mark classes or functions with @riverpod for code generation:

@riverpod
class Counter extends _$Counter {
  @override
  int build() => 0;

  void increment() => state++;
}

2. Consuming State

Use ConsumerWidget or ConsumerStatefulWidget:

class CounterView extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Text('$count');
  }
}

3. Provider Types

Type	Use For	Syntax
StateProvider	Simple state	@riverpod class X extends _$X
AsyncNotifier	Async loading	@riverpod class X extends _$X with Future
StreamProvider	Real-time data	@riverpod Stream<T> func(Ref ref)
Family providers	Parameterized	@riverpod class X extends Family<X, Args>

Code Patterns

Pattern 1: AsyncNotifier for API Calls

@riverpod
class UserController extends _$UserController {
  @override
  Future<User> build(String userId) async {
    final dio = ref.watch(dioProvider);
    final response = await dio.get('/users/$userId');
    return User.fromJson(response.data);
  }

  Future<void> updateUser(User user) async {
    // Optimistic update
    final previous = await future;
    state = AsyncData(user);

    try {
      await ref.read(dioProvider).put('/users/${user.id}', user.toJson());
    } catch (e) {
      state = AsyncError(e, StackTrace.current);
    }
  }
}

Pattern 2: Combining Providers

@riverpod
List<Todo> filteredTodos(Ref ref) {
  final todos = ref.watch(todosProvider);
  final filter = ref.watch(filterProvider);

  return switch (filter) {
    Filter.all => todos,
    Filter.completed => todos.where((t) => t.completed).toList(),
    Filter.uncompleted => todos.where((t) => !t.completed).toList(),
  };
}

Pattern 3: Dependency Injection

@riverpod
Dio dio(Ref ref) {
  final baseUrl = ref.watch(baseUrlProvider);
  return Dio(BaseOptions(baseUrl: baseUrl));
}

Pattern 4: AsyncValue Pattern Matching

class AsyncWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final data = ref.watch(asyncProvider);

    return switch (data) {
      AsyncData(:final value) => Text('$value'),
      AsyncError(:final error, :final stackTrace) => ErrorWidget(error),
      AsyncLoading() => const CircularProgressIndicator(),
    };
  }
}

Provider Modifiers

Family - Parameterized Providers

@riverpod
Future<User> user(UserRef ref, String userId) async {
  return await api.getUser(userId);
}

// Usage
ref.watch(userProvider('123'));

AutoDispose - Automatic Cleanup

@Riverpod(keepAlive: false)
Future<User> temporaryUser(TemporaryUserRef ref, String id) async {
  ref.onDispose(() {
    // Cleanup logic
  });
  return await api.getUser(id);
}

Widget Patterns

ConsumerWidget Pattern

class MyWidget extends ConsumerWidget {
  const MyWidget({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final value = ref.watch(myProvider);
    return Text('$value');
  }
}

ConsumerStatefulWidget Pattern

class MyPage extends ConsumerStatefulWidget {
  const MyPage({super.key});

  @override
  ConsumerState<MyPage> createState() => _MyPageState();
}

class _MyPageState extends ConsumerState<MyPage> {
  @override
  void initState() {
    super.initState();
    ref.read(myProvider.notifier).load();
  }

  @override
  Widget build(BuildContext context) {
    final state = ref.watch(myProvider);
    return Scaffold(body: Text('$state'));
  }
}

HookConsumerWidget (with flutter_hooks)

class HookWidget extends HookConsumerWidget {
  const HookWidget({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final controller = useTextController();
    final count = ref.watch(counterProvider);
    
    return TextField(controller: controller);
  }
}

Code Generation Workflow

1. Add annotation: @riverpod or @Riverpod()
2. Define class extending _$ClassName or function
3. Run: flutter pub run build_runner watch --delete-conflicting-outputs
4. Generated file: .g.dart extension

Essential Commands

# Generate once
flutter pub run build_runner build --delete-conflicting-outputs

# Watch for changes (recommended during development)
flutter pub run build_runner watch --delete-conflicting-outputs

Testing

testWidgets('counter increments', (tester) async {
  await tester.pumpWidget(
    ProviderScope(
      child: MaterialApp(home: CounterView()),
    ),
  );

  expect(find.text('0'), findsOneWidget);
});

ref Methods

Method	Use For
ref.watch(provider)	Rebuild when value changes
ref.read(provider)	One-time read, no rebuild
ref.listen(provider, cb)	Side effects on change
ref.refresh(provider)	Force reload
ref.invalidate(provider)	Mark as needing refresh

Best Practices

See BEST_PRACTICES.md for detailed guidelines on:

• Provider architecture
• Avoiding common pitfalls
• Performance optimization
• Testing strategies