mcpField
R
riverpod-mutations

riverpod-mutations

github.com/serverpodDevelopment1078 installsUpdated 34w ago
Repository

About riverpod-mutations

riverpod-mutations is a skill covering Riverpod’s experimental Mutations API. It is for developers who want to keep the state of a single async operation separate from their main provider state, with guidance on listening, triggering, keyed instances, and reset behavior.

Key features

  1. 01Represent a single async operation
  2. 02Watch idle, pending, success, and error states
  3. 03Run callbacks that return operation results
  4. 04Manage multiple keyed mutation instances
  5. 05Reset mutation state manually

Use cases

  1. 01Show operation progress and results in a UI
  2. 02Keep loading and error state out of main provider state
  3. 03Track operations separately for individual list items

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/serverpod/skills-registry --skill riverpod-mutations

After installing, type/riverpod-mutationsin Claude Code to confirm it loaded.

Details

From the project README

Riverpod — Mutations (experimental)

Instructions

Mutations represent a single async operation the UI can react to (e.g. "add todo" in progress, succeeded, or failed). They keep loading/error/success out of your main provider state. The API is experimental and may change.

Defining a mutation

Create a Mutation<T> instance (T is the result type, optional):

final addTodo = Mutation<Todo>();

Typically store it as a global or static final on a Notifier.

Listening

Use ref.watch in a Consumer (or inside a provider) to drive the UI:

final addTodoState = ref.watch(addTodo);

// In build:
backgroundColor: switch (addTodoState) {
  MutationError() => const WidgetStatePropertyAll(Colors.red),
  _ => null,
},
if (addTodoState is MutationPending) ...[
  const SizedBox(width: 8),
  const CircularProgressIndicator(),
],
States
  • MutationIdle — Not started or reset.
  • MutationPending — In progress.
  • MutationSuccess — Succeeded; result available.
  • MutationError — Failed; error available.

Use a switch on the state to handle each case.

Triggering

Call Mutation.run(ref, callback). The callback receives a transaction object (e.g. tsx) to access providers and must return a value of type T:

addTodo.run(ref, (tsx) async {
  final todoNotifier = tsx.get(todoNotifierProvider.notifier);
  final createdTodo = await todoNotifier.addTodo('Eat a cookie');
  return createdTodo;
});

Use tsx.get(provider) to keep providers alive for the duration of the mutation.

Keyed mutations

Pass a key to have multiple instances (e.g. one mutation per list item):

ref.watch(deleteItemMutation(itemId));
deleteItemMutation(itemId).run(ref, (tsx) async { ... });
Resetting

Mutations reset to Idle when they complete or when all listeners are removed. To reset manually:

addTodo.reset(ref);

See the official Riverpod docs for the latest mutation API and generics.

Comments

Markdown supported