Introduction

What is Shard?

Shard is a lightweight, powerful state management solution for Flutter applications. Built on Flutter's ChangeNotifier, Shard provides a clean and intuitive API for managing application state with minimal boilerplate.

Why Shard?

Simple & Intuitive

Shard follows Flutter's reactive programming model. Create a shard, emit state changes, and widgets automatically rebuild when state changes.

class CounterShard extends Shard<int> {
  CounterShard() : super(0);
  
  void increment() {
    emit(state + 1);
  }
}

Built-in Persistence

Automatically save and restore state with PersistentShard. Choose your preferred local storage solution (SharedPreferences, Hive, Isar, etc.) - no need for separate persistence libraries or complex setup.

class TodoShard extends PersistentShard<TodoState> {
  @override
  String get persistenceKey => 'todos';
  
  TodoShard() : super(
    const TodoState(todos: []),
    storageFactory: () => SharedPreferencesStorage.create(), // Or HiveStorage, IsarStorage, etc.
    serializer: TodoSerializer(),
  );
}

Performance Optimizations

Built-in debounce and throttle mixins help prevent excessive state updates and API calls.

void updateSearchQuery(String query) {
  debounce('search', () {
    emit(state.copyWith(searchQuery: query));
  }, duration: const Duration(milliseconds: 500));
}

Seamless Flutter Integration

Widgets like ShardProvider, ShardBuilder, and ShardSelector make it easy to integrate with Flutter's widget tree. Context extensions provide convenient access.

// Using ShardBuilder
ShardBuilder<CounterShard, int>(
  builder: (context, count) {
    return Text('Count: $count');
  },
)

// Using context extensions
context.read<CounterShard>().increment();

Key Features

• Type-Safe: Full type safety with Dart's type system
• Persistence: Built-in state persistence with customizable serializers
• Debounce & Throttle: Prevent excessive updates and API calls
• Observers: Monitor state changes and handle errors
• Testable: Clear separation of concerns, easy to test
• Lightweight: Minimal dependencies, no external state management libraries

Next Steps

Ready to get started? Check out the Installation Guide to add Shard to your project.