create-cubit

name: create-cubit description: Create a new Cubit using mix() function for automatic loading and error state tracking

Create a Cubit with bloc_superpowers

This skill creates a new Cubit that uses the mix() function for automatic loading/error state tracking.

What This Skill Does

Creates a Cubit class that:

• Uses the mix() function to wrap async operations
• Automatically tracks loading states (no isLoading field needed)
• Automatically tracks error states (no errorMessage field needed)
• Throws UserException for user-facing errors

Instructions

Step 1: Gather Requirements

Ask the user:

1. Cubit name: What should the Cubit be called? (e.g., UserCubit, ProductCubit)
2. State type: What data does the state hold? (e.g., User, List<Product>, or a custom state class)
3. Methods: What async operations should the Cubit perform? (e.g., loadData, save, delete)

Step 2: Create the Cubit

Create a Cubit that uses mix() with key: this:

import 'package:bloc_superpowers/bloc_superpowers.dart';
import 'package:flutter_bloc/flutter_bloc.dart';

class UserCubit extends Cubit<User?> {
  UserCubit() : super(null);

  void loadUser() => mix(
    key: this,
    () async {
      final user = await api.getUser();
      if (user == null) throw UserException('Failed to load user');
      emit(user);
    },
  );
}

Step 3: Create the State Class (if needed)

For simple state (single value), use the value type directly:

class UserCubit extends Cubit<User?> { ... }

For complex state with multiple fields, create a state class without isLoading or errorMessage:

class UserState {
  final User? user;
  final List<Post> posts;

  const UserState({this.user, this.posts = const []});

  UserState copyWith({User? user, List<Post>? posts}) {
    return UserState(
      user: user ?? this.user,
      posts: posts ?? this.posts,
    );
  }
}

class UserCubit extends Cubit<UserState> {
  UserCubit() : super(const UserState());

  void loadUser() => mix(
    key: this,
    () async {
      final user = await api.getUser();
      if (user == null) throw UserException('Failed to load user');
      emit(state.copyWith(user: user));
    },
  );

  void loadPosts() => mix(
    key: this,
    () async {
      final posts = await api.getPosts();
      emit(state.copyWith(posts: posts));
    },
  );
}

Step 4: Use in Widgets

Show loading and error states using context extensions:

class UserWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Show loading indicator while loading
    if (context.isWaiting(UserCubit)) {
      return const CircularProgressIndicator();
    }

    // Show error message if failed
    if (context.isFailed(UserCubit)) {
      return Text('Error: ${context.getException(UserCubit)}');
    }

    // Show the data
    final user = context.watch<UserCubit>().state;
    return Text('Hello, ${user?.name ?? "Guest"}');
  }
}

Syntax Variations

The mix() function supports multiple declaration patterns:

// Arrow function with void return (most common)
void loadUser() => mix(
  key: this,
  () async { ... },
);

// Arrow function with Future return (when caller needs to await)
Future<void> loadUser() => mix(
  key: this,
  () async { ... },
);

// Block syntax (when you need additional logic before/after mix)
void loadUser() {
  mix(
    key: this,
    () async { ... },
  );
}

Available Parameters

The mix() function accepts optional parameters for enhanced behavior:

Each parameter has a dedicated skill for detailed usage.

Key Patterns

Using key: this

When you use key: this inside a Cubit method, it becomes the Cubit's runtimeType (e.g., UserCubit), not the instance. This means:

• All methods in the Cubit share the same loading/error state
• Widgets check state using the Cubit type: context.isWaiting(UserCubit)

Parameterized Keys (for granular tracking)

For methods with parameters where you need separate loading states per item:

void loadUser(String userId) => mix(
  key: (UserCubit, userId),  // Composite key using a record
  () async {
    final user = await api.getUser(userId);
    emit(state.copyWith(users: {...state.users, userId: user}));
  },
);

// In widget:
if (context.isWaiting((UserCubit, userId))) { ... }

Throwing UserException

When something goes wrong, throw UserException with a user-friendly message:

void loadUser() => mix(
  key: this,
  () async {
    final user = await api.getUser();
    if (user == null) {
      throw UserException('Could not load your profile. Please try again.');
    }
    emit(user);
  },
);

Complete Example

import 'package:bloc_superpowers/bloc_superpowers.dart';
import 'package:flutter_bloc/flutter_bloc.dart';

// State class (no isLoading or errorMessage!)
class TodoState {
  final List<Todo> todos;

  const TodoState({this.todos = const []});

  TodoState copyWith({List<Todo>? todos}) {
    return TodoState(todos: todos ?? this.todos);
  }
}

// Cubit with mix()
class TodoCubit extends Cubit<TodoState> {
  TodoCubit() : super(const TodoState());

  void loadTodos() => mix(
    key: this,
    () async {
      final todos = await api.getTodos();
      emit(state.copyWith(todos: todos));
    },
  );

  void addTodo(String title) => mix(
    key: this,
    () async {
      final newTodo = await api.createTodo(title);
      emit(state.copyWith(todos: [...state.todos, newTodo]));
    },
  );

  void deleteTodo(String id) => mix(
    key: (TodoCubit, 'delete', id),  // Separate key per delete operation
    () async {
      await api.deleteTodo(id);
      emit(state.copyWith(
        todos: state.todos.where((t) => t.id != id).toList(),
      ));
    },
  );
}

// Widget
class TodoScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    if (context.isWaiting(TodoCubit)) {
      return const Center(child: CircularProgressIndicator());
    }

    if (context.isFailed(TodoCubit)) {
      return Center(
        child: Column(
          children: [
            Text('Error: ${context.getException(TodoCubit)}'),
            ElevatedButton(
              onPressed: () => context.read<TodoCubit>().loadTodos(),
              child: const Text('Retry'),
            ),
          ],
        ),
      );
    }

    final todos = context.watch<TodoCubit>().state.todos;
    return ListView.builder(
      itemCount: todos.length,
      itemBuilder: (context, index) => TodoTile(todo: todos[index]),
    );
  }
}