> ## Content Index
> Fetch the complete content index at: https://arkar.dev/llms.txt
> Use this file to discover other available public pages before exploring further.

# AtomicFlutter v0.3.0: Lightweight Reactive State Management for Flutter
- URL: https://arkar.dev/atomicflutter-v0-3-0-lightweight-reactive-state-management-for-flutter/
- Published: 2025-12-05T14:57:22.000Z
- Updated: 2025-12-28T10:46:26.000Z
- Description: Zero dependencies. Maximum power. Minimal boilerplate.
- Author: Arkar Min Tun
- Tags: atomic_flutter, flutter

## The State Management Problem

  
If you've built Flutter apps, you know the struggle. State management solutions are either:

- **Too complex** \- Steep learning curves, massive boilerplate (looking at you, BLoC)
- **Too simple** \- Great for demos, but don't scale (setState anyone?)
- **Too opinionated** \- Force you into specific patterns
- **Too heavy** \- Pulling in huge dependency trees

What if there was a better way?

## Introducing AtomicFlutter

**AtomicFlutter** is a lightweight, reactive state management library that brings fine-grained reactivity to Flutter. Think of it as **Signals** for Flutter, or **Jotai** for React developers.

### Why "AtomicFlutter"?  

Atoms are the smallest units of state. Each atom:

- Manages a single piece of state
- Notifies only the widgets that care
- Automatically disposes when no longer needed
- Composes beautifully with other atoms

No global stores. No reducers. No actions. Just **simple, reactive state**.

### Quick Example

Here's a complete counter app in **23 lines of code**:

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

final counterAtom = Atom<int>(0);

class CounterApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: AtomBuilder(
            atom: counterAtom,
            builder: (context, count) => Text('$count'),
          ),
        ),
        floatingActionButton: FloatingActionButton(
          onPressed: () => counterAtom.update((c) => c + 1),
          child: Icon(Icons.add),
        ),
      ),
    );
  }
}
```

No providers. No context. No boilerplate. **Just works.**

---

## **Core Features**

### **1\. Fine-Grained Reactivity**

Only rebuild what changed. AtomicFlutter tracks dependencies at the atom level, not the widget tree level.

```dart
final userAtom = Atom<User>(currentUser);
final nameAtom = computed(() => userAtom.value.name, tracked: [userAtom]);

// This widget only rebuilds when the NAME changes
AtomBuilder(
  atom: nameAtom,
  builder: (context, name) => Text(name),
)
```

### **2\. Async State Made Easy**

```dart
final productsAtom = AsyncAtom<List<Product>>();

// Execute async operation
await productsAtom.execute(() => api.getProducts());

// UI handles all states automatically
AsyncBuilder<List<Product>>(
  atom: productsAtom,
  loading: (context) => CircularProgressIndicator(),
  error: (context, error) => ErrorWidget(error),
  builder: (context, products) => ProductList(products),
)
```

### **3\. Automatic Memory Management**

Atoms dispose themselves when no longer used. No memory leaks, no manual cleanup (unless you want it).

```dart
// Auto-disposes after 2 minutes of no listeners
final tempAtom = Atom<String>('temp', autoDispose: true);

// Never disposes (global state)
final themeAtom = Atom<ThemeMode>(ThemeMode.light, autoDispose: false);
```

### **4\. Powerful Extensions**

Transform, filter, debounce, throttle - all built-in:

```dart
// Debounced search
final searchAtom = Atom<String>('');
final debouncedSearch = searchAtom.debounce(Duration(milliseconds: 300));

// Only even numbers
final numberAtom = Atom<int>(0);
final evenNumbers = numberAtom.where((n) => n % 2 == 0);

// Double the values
final doubled = numberAtom.map((n) => n * 2);
```

---

## **What's New in v0.3.0**

A **massive update** has been shipped with critical bug fixes and quality improvements:

### Critical Bug Fixes

**Memory Leak Fixes** \- Fixed memory leaks in **11 extension methods**:

- All `debounce`, `throttle`, `map`, `where`, `combine` methods now properly cleanup
- Bidirectional cleanup: both source and derived atoms dispose correctly
- Timer cleanup prevents resource leaks

**Before v0.3.0:**

```dart
final debounced = searchAtom.debounce(Duration(seconds: 1));
// ❌ Memory leak - listener never removed!

```

**After v0.3.0:**

```dart
final debounced = searchAtom.debounce(Duration(seconds: 1));
// ✅ Properly cleans up when disposed
debounced.dispose(); // All listeners removed
```

### Type Safety Improvements

**Computed Atoms are Now Read-Only:**

```dart
final total = computed(() => price.value * quantity.value, tracked: [price, quantity]);

total.set(999);
// ❌ Throws UnsupportedError with clear message
// "Cannot directly set value of computed atom. Update its dependencies instead."
```

**Circular Dependency Detection:**

```dart
final a = Atom<int>(0);
final b = computed(() => a.value + 1, tracked: [a]);
final c = computed(() => b.value + a.value, tracked: [a, b]); // ✅ Works fine

// But this throws:
final d = computed(() => c.value + 1, tracked: [c]);
final e = computed(() => d.value + 1, tracked: [d, e]); // ❌ Circular!
// StateError: Circular dependency detected

```

### Error Isolation

Failing listeners no longer crash your app:

```dart
atom.addListener((value) {
  throw Exception('Oops!'); // ❌ Before: App crashes
});

atom.addListener((value) {
  updateUI(value); // ✅ After: This still runs!
});

```

### Complete v0.3.0 Changes

- Fixed memory leaks in 11 extension methods
- Computed atoms are type-safe (can't mutate)
- Circular dependency detection
- Error isolation in listeners
- StreamController proper disposal
- Edge case fixes (empty lists, initial states)
- 31+ new test cases
- Enhanced documentation

---

## Advanced Patterns

### Domain-Specific Atoms

Encapsulate business logic in custom atoms:

```dart
class CartAtom extends Atom<Cart> {
  CartAtom() : super(const Cart(), autoDispose: false);

  void addProduct(Product product, int quantity) {
    update((cart) => cart.addItem(
      CartItem(product: product, quantity: quantity),
    ));
    _saveToBackend(); // Optimistic update!
  }

  void removeProduct(int productId) {
    update((cart) => cart.removeItem(productId));
    _saveToBackend();
  }

  Future<void> _saveToBackend() async {
    await api.saveCart(value);
  }
}

```

### Async Retry Logic

Exponential backoff built-in:

```dart
final dataAtom = AsyncAtom<Data>();

await dataAtom.executeWithRetry(
  () => api.fetchData(),
  maxRetries: 3,
  delay: Duration(seconds: 1), // 1s, 2s, 3s delays
);

```

### Optimistic Updates

Update UI immediately, sync later:

```dart
void likePost(Post post) {
  // Update UI instantly
  postsAtom.update((posts) =>
    posts.map((p) => p.id == post.id ? p.copyWith(liked: true) : p).toList()
  );

  // Sync with backend
  api.likePost(post.id).catchError((e) {
    // Rollback on error
    postsAtom.update((posts) =>
      posts.map((p) => p.id == post.id ? p.copyWith(liked: false) : p).toList()
    );
  });
}

```

### Performance Optimization

Use `AtomSelector` to rebuild only when specific fields change:

```dart
// Rebuilds on EVERY cart change
AtomBuilder(
  atom: cartAtom,
  builder: (context, cart) => Text('\$${cart.totalPrice}'),
)

// ✅ Rebuilds ONLY when totalPrice changes
cartAtom.select<double>(
  selector: (cart) => cart.totalPrice,
  builder: (context, total) => Text('\$$total'),
)

```

---

## Real-World Example: E-Commerce App

Here's how you'd structure a production app:

```dart
// Domain atoms
final productsAtom = AsyncAtom<List<Product>>();
final cartAtom = CartAtom();
final userAtom = Atom<User?>(null);

// Computed atoms
final cartCountAtom = computed<int>(
  () => cartAtom.value.itemCount,
  tracked: [cartAtom],
);

final cartTotalAtom = computed<double>(
  () => cartAtom.value.totalPrice,
  tracked: [cartAtom],
);

// Search with debouncing
final searchQueryAtom = Atom<String>('');
final debouncedSearchAtom = searchQueryAtom.debounce(
  Duration(milliseconds: 500),
);

final filteredProductsAtom = computed<List<Product>>(
  () {
    final products = productsAtom.value;
    final query = debouncedSearchAtom.value;

    if (!products.hasValue || query.isEmpty) return [];

    return products.value
      .where((p) => p.name.toLowerCase().contains(query.toLowerCase()))
      .toList();
  },
  tracked: [productsAtom, debouncedSearchAtom],
);

```

**UI Layer:**

```dart
class ProductsScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Products'),
        actions: [
          AtomBuilder(
            atom: cartCountAtom,
            builder: (context, count) => Badge(
              label: Text('$count'),
              child: Icon(Icons.shopping_cart),
            ),
          ),
        ],
      ),
      body: Column(
        children: [
          // Search bar
          TextField(
            onChanged: searchQueryAtom.set,
            decoration: InputDecoration(
              hintText: 'Search (debounced 500ms)',
            ),
          ),

          // Products list
          Expanded(
            child: AsyncBuilder<List<Product>>(
              atom: productsAtom,
              enableRefresh: true,
              loading: (context) => CircularProgressIndicator(),
              error: (context, error) => ErrorRetryWidget(error),
              builder: (context, products) {
                return AtomBuilder(
                  atom: filteredProductsAtom,
                  builder: (context, filtered) => ProductList(filtered),
                );
              },
            ),
          ),
        ],
      ),
    );
  }
}

```

---

## Comparison with Other Solutions

| Feature                  | AtomicFlutter | Provider  | Riverpod | BLoC           | GetX       |
| ------------------------ | ------------- | --------- | -------- | -------------- | ---------- |
| **Dependencies**         | 0             | 2         | 3        | 4+             | 1          |
| **Learning Curve**       | ⭐ Easy        | ⭐⭐ Medium | ⭐⭐⭐ Hard | ⭐⭐⭐⭐ Very Hard | ⭐⭐ Medium  |
| **Boilerplate**          | Minimal       | Medium    | Medium   | Heavy          | Minimal    |
| **Fine-grained Updates** | ✅ Yes         | ❌ No      | ✅ Yes    | ❌ No           | ⚠️ Partial |
| **Async Built-in**       | ✅ Yes         | ❌ No      | ✅ Yes    | ✅ Yes          | ✅ Yes      |
| **Auto Disposal**        | ✅ Yes         | ❌ No      | ✅ Yes    | ❌ No           | ⚠️ Manual  |
| **Type Safety**          | ✅ Strong      | ✅ Strong  | ✅ Strong | ✅ Strong       | ⚠️ Weak    |
| **DevTools**             | Planned       | ✅ Yes     | ✅ Yes    | ✅ Yes          | ✅ Yes      |

---

## Performance

**AtomicFlutter** is designed for **efficiency**. Here's how:

1. **Fine-grained reactivity** \- Only affected widgets rebuild, not entire subtrees
2. **Atom-level tracking** \- No context lookups, no widget tree traversal
3. **Efficient equality checks** \- Uses `identical()` first (fast path), then `==`
4. **Lazy evaluation** \- Computed atoms only recompute when dependencies actually change
5. **Smart disposal** \- Reference counting prevents unnecessary work

The fine-grained reactivity means that in apps with complex state, you'll see fewer rebuilds and better performance compared to solutions that rebuild entire subtrees.

---

## Migration Guide

### From Provider

**Before (Provider):**

```dart
class CounterProvider extends ChangeNotifier {
  int _count = 0;
  int get count => _count;

  void increment() {
    _count++;
    notifyListeners();
  }
}

// In widget
Provider.of<CounterProvider>(context).increment();
Consumer<CounterProvider>(
  builder: (context, counter, child) => Text('${counter.count}'),
)

```

**After (AtomicFlutter):**

```dart
final counterAtom = Atom<int>(0);

// In widget
counterAtom.update((c) => c + 1);
AtomBuilder(
  atom: counterAtom,
  builder: (context, count) => Text('$count'),
)

```

### From Riverpod

**Before (Riverpod):**

```dart
final counterProvider = StateProvider<int>((ref) => 0);

// In widget
final count = ref.watch(counterProvider);
ref.read(counterProvider.notifier).state++;

```

**After (AtomicFlutter):**

```dart
final counterAtom = Atom<int>(0);

// In widget
AtomBuilder(
  atom: counterAtom,
  builder: (context, count) => Text('$count'),
)
counterAtom.update((c) => c + 1);

```

---

## When to Use AtomicFlutter

**Perfect for:**

- Apps of any size (small to large)
- Teams that want minimal boilerplate
- Developers familiar with Signals/Jotai/Recoil
- Projects that need fine-grained reactivity
- Apps with complex async state
- When you want automatic memory management

**Consider alternatives if:**

- You need mature DevTools (coming soon!)
- Your team is already invested in another solution
- You need very specific patterns (like Redux time-travel)

---

## Getting Started

### Installation

```yaml
dependencies:
  atomic_flutter: ^0.3.0

```

### Basic Usage

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

// 1. Create atoms
final nameAtom = Atom<String>('John');
final ageAtom = Atom<int>(25);

// 2. Computed atoms
final greetingAtom = computed<String>(
  () => 'Hello, ${nameAtom.value}! You are ${ageAtom.value} years old.',
  tracked: [nameAtom, ageAtom],
);

// 3. Use in widgets
AtomBuilder(
  atom: greetingAtom,
  builder: (context, greeting) => Text(greeting),
)

```

### Async Example

```dart
final userAtom = AsyncAtom<User>();

// Load data
await userAtom.execute(() => api.getUser());

// Handle all states
AsyncBuilder<User>(
  atom: userAtom,
  loading: (context) => Spinner(),
  error: (context, error) => ErrorWidget(error),
  builder: (context, user) => UserProfile(user),
)

```

---

## Documentation & Resources

- **Documentation**: [pub.dev/packages/atomic\_flutter](https://pub.dev/packages/atomic%5Fflutter?ref=arkar.dev)
- **GitHub**: [github.com/arkarmintun1/atomic\_flutter](https://github.com/arkarmintun1/atomic%5Fflutter?ref=arkar.dev)
- **Examples**: Complete e-commerce app in `/example`
- **Tests**: 100+ test cases for reliability

---

## What's Next?

We're working on:

- **DevTools Extension** \- Visual atom inspector
- **Performance Monitoring** \- Track atom updates and rebuilds
- **Time-Travel Debugging** \- Undo/redo state changes
- **Persistence Layer** \- Built-in local storage
- **Code Generation** \- Reduce boilerplate even more

---

## Community

Join the growing community:

- **Discord**: \[[Link](https://discord.gg/uemGJp6Z7k?ref=arkar.dev)\]
- **Twitter**: \[[@atomic\_flutter\_](https://x.com/atomic%5Fflutter%5F?ref=arkar.dev)\]

---

## Conclusion

AtomicFlutter brings **simplicity** back to Flutter state management without sacrificing power. With v0.3.0, it's more robust than ever—zero memory leaks, type-safe, and production-ready.

**Try it today:**

```bash
flutter pub add atomic_flutter

```

Then build something amazing. 🚀