playbooks

home / skills / medz / oref / oref

oref skill

/skills/oref

This skill provides guidance for using the Oref Flutter signals library, including signals, computed, effects, DevTools, and troubleshooting.

npx playbooks add skill medz/oref --skill oref

Review the files below or copy the command above to add this skill to your agents.

Files (9)
SKILL.md
3.4 KB
---
name: oref
description: Guidance for using the Oref Flutter signals/state management library and its DevTools/analyzer tooling. Use when answering questions about installing Oref, creating signals/computed/effects, async data, reactive collections, SignalBuilder usage, analyzer lints, DevTools extension setup/usage, or troubleshooting Oref behavior.
---

# Oref

> Based on the Oref docs and repository examples. Use BuildContext-bound APIs inside widget builds when possible.

## Preferences

- Match the user's language.
- Prefer concise, runnable snippets over long explanations.
- Use `signal(context, ...)`/`computed(context, ...)`/`effect(context, ...)` inside `build`.
- Use `null` context only outside widgets, and keep the dispose handle.
- Use `SignalBuilder` to scope rebuilds to small subtrees.
- Use `batch()` for multi-step updates or collection mutations.
- Avoid writing to signals inside `computed` getters.
- Call hooks unconditionally at the top level of a build scope.

## Core

| Topic             | Description                                                                 | Reference                                        |
| ----------------- | --------------------------------------------------------------------------- | ------------------------------------------------ |
| Quick Start       | Install + minimal signal/computed/effect usage                              | [quick-start](references/quick-start.md)         |
| Reactivity Core   | Signals, computed, writableComputed, effects, batch, untrack, SignalBuilder | [core-api](references/core-api.md)               |
| Hooks & Lifecycle | Hook ordering rules, onMounted/onUnmounted, cleanup                         | [hooks-lifecycle](references/hooks-lifecycle.md) |
| Async Data        | `useAsyncData` lifecycle and rendering                                      | [async-data](references/async-data.md)           |
| Collections       | ReactiveList/Map/Set patterns                                               | [collections](references/collections.md)         |

## Tooling

| Topic           | Description                     | Reference                                        |
| --------------- | ------------------------------- | ------------------------------------------------ |
| Analyzer Lints  | Plugin setup + lint catalog     | [analyzer-lints](references/analyzer-lints.md)   |
| DevTools        | Extension setup + runtime notes | [devtools](references/devtools.md)               |
| Troubleshooting | Common pitfalls and fixes       | [troubleshooting](references/troubleshooting.md) |

## Quick Reference

### Minimal widget

```dart
import 'package:flutter/material.dart';
import 'package:oref/oref.dart';

class Counter extends StatelessWidget {
  const Counter({super.key});

  @override
  Widget build(BuildContext context) {
    final count = signal(context, 0);
    final doubled = computed(context, (_) => count() * 2);

    return Column(
      children: [
        Text('Count: ${count()} / ${doubled()}'),
        TextButton(onPressed: () => count.set(count() + 1), child: const Text('Add')),
      ],
    );
  }
}
```

### Key imports

```dart
import 'package:oref/oref.dart';
```

## Response workflow

1. Identify the question type and open the matching reference.
2. Provide the smallest snippet that answers the question.
3. Ask for missing context only if required (Flutter version, target platform, existing code).
4. Avoid guessing versions; read the user's `pubspec.yaml` or ask them to confirm.

Overview

This skill provides focused guidance for using Oref, a high-performance Flutter signals and state-management library, plus its DevTools and analyzer tooling. It helps you install Oref, create signals/computed/effects, manage async data and reactive collections, and use SignalBuilder for scoped rebuilds. It also covers analyzer lints, DevTools setup, and common troubleshooting patterns.

How this skill works

I inspect the question to match it to Oref topics (core reactivity, hooks/lifecycle, async data, collections, lints, DevTools, troubleshooting). I return concise runnable snippets when possible and prefer BuildContext-bound APIs inside widget builds (signal(context,...), computed(context,...), effect(context,...)). Outside widgets I recommend null context with an explicit dispose handle. I suggest tooling steps for analyzer plugin and DevTools extension setup when relevant.

When to use it

  • When you need fast, fine-grained reactive state inside Flutter widgets.
  • When scoping rebuilds to a small subtree using SignalBuilder improves performance.
  • When implementing derived state using computed or side effects using effect.
  • When integrating async data with lifecycle-aware useAsyncData patterns.
  • When configuring analyzer lints or using the Oref DevTools for runtime inspection.

Best practices

  • Call hooks (signal/computed/effect) unconditionally at the top level of a widget build.
  • Prefer signal(context, ...) / computed(context, ...) inside build; use null context only outside widgets and keep the dispose handle.
  • Use SignalBuilder to restrict rebuilds to minimal subtree areas instead of rebuilding entire widgets.
  • Use batch(...) for multi-step updates or when mutating reactive collections to avoid extra recomputations.
  • Never write to signals inside computed getters; keep computed pure and side-effect-free.

Example use cases

  • Simple counter: signal in build, computed for derived value, Button increments using count.set.
  • Scoped UI updates: wrap a small part of the widget tree with SignalBuilder to limit rebuilds.
  • Async data loading: use useAsyncData to fetch and manage loading/error states with proper cleanup.
  • Reactive collections: use ReactiveList/Map with batch() for multiple mutations to avoid redundant updates.
  • DevTools: install the DevTools extension and enable runtime inspection to visualize signals and computed values.

FAQ

Should I call signal(...) inside build or outside?

Prefer signal(context, ...) inside build so Oref can scope lifecycle to the widget. Use null context only for long-lived objects and store the dispose handle.

How do I avoid extra rebuilds for small widgets?

Wrap the small widget subtree with SignalBuilder so only that subtree rebuilds when the referenced signals change.

Can computed have side effects or write to signals?

No. Keep computed getters pure. Use effect(...) for side effects and explicit writes.