# Riverpod Mutations

> Use Riverpod mutations for UI-driven async operations like form submit; Mutation.run, MutationIdle/Pending/Success/Error, Mutation.reset, keyed mutations. Use when showing loading/error/success for a single action (e.g. submit button) without polluting provider state. Use this skill when the user asks about mutations, loading state for actions, or form submission with Riverpod.

- **Type:** Skill
- **Install:** `agentstack add skill-serverpod-skills-registry-riverpod-mutations`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [serverpod](https://agentstack.voostack.com/s/serverpod)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** BSD-3-Clause
- **Upstream author:** [serverpod](https://github.com/serverpod)
- **Source:** https://github.com/serverpod/skills-registry/tree/main/skills/riverpod/riverpod-mutations

## Install

```sh
agentstack add skill-serverpod-skills-registry-riverpod-mutations
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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` instance (T is the result type, optional):

```dart
final addTodo = Mutation();
```

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:

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

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

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

```dart
addTodo.reset(ref);
```

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [serverpod](https://github.com/serverpod)
- **Source:** [serverpod/skills-registry](https://github.com/serverpod/skills-registry)
- **License:** BSD-3-Clause

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-serverpod-skills-registry-riverpod-mutations
- Seller: https://agentstack.voostack.com/s/serverpod
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.