riverpod-offline

Riverpod — Offline persistence (experimental)

Instructions

Offline persistence stores provider state on device so it survives restarts and works offline. Riverpod is storage-agnostic; packages like riverpod_sqflite provide a Storage implementation. Only Notifier-based providers can be persisted. The feature is experimental.

Creating a Storage

Install a package (e.g. riverpod_sqflite + sqflite) and create a Storage. With SQFlite:

final storageProvider = FutureProvider<Storage<String, String>>((ref) async {
  return JsonSqFliteStorage.open(
    join(await getDatabasesPath(), 'riverpod.db'),
  );
});

Persisting a notifier

Inside the notifier's build, call persist with: the Storage (e.g. ref.watch(storageProvider.future)), a unique key, and encode/ decode for your state. Do not await persist; Riverpod handles it.

class TodoList extends AsyncNotifier<List<Todo>> {
  @override
  Future<List<Todo>> build() async {
    persist(
      ref.watch(storageProvider.future),
      key: 'todo_list',
      encode: (todos) => todos.map((todo) => {'task': todo.task}).toList(),
      decode: (json) => (json as List).map((todo) => Todo(task: todo['task'] as String)).toList(),
    );
    return fetchTodosFromServer();
  }
}

Keys

• Unique across all persisted providers (same key = same row, risk of corruption).
• Stable across restarts (changing the key loses restored state).
• For family providers, include the parameter in the key.

JsonPersist (code generation)

With riverpod_sqflite and codegen, use @JsonPersist() so key/encode/decode are generated:

@riverpod
@JsonPersist()
class TodoList extends _$TodoList {
  @override
  Future<List<Todo>> build() async {
    persist(ref.watch(storageProvider.future));
    return fetchTodosFromServer();
  }
}

Cache duration

By default state is cached for a short time (e.g. 2 days). For long-lived data (e.g. user preferences), set StorageOptions: