Create use-cases for Widgetbook: Strategies and Automation Tools

Organizations adopting Widgetbook often have established applications with extensive component libraries. When teams recognize the need for a comprehensive widget catalog to enhance collaboration, they face time constraints in implementing the migration. This article explores efficient strategies and tools for cataloging existing components to leverage Widgetbook and Widgetbook Cloud effectively.

What is Widgetbook?

Flutter teams typically work with design systems created by freelancers or in-house design teams. While Figma’s component-based approach naturally generates a comprehensive catalog through best practices, Flutter developers face challenges after implementing these components as Widgets and collecting feedback on the adjusted or added Widgets. The traditional approach of sharing screenshots via Slack or Teams for assessment proves inefficient and cumbersome.

Widgetbook revolutionizes this workflow by providing a specialized environment for component visualization and testing. Through its comprehensive feature set, teams can:

• Efficiently preview and test widgets in isolation and with different hard-to-reach states
• Ensure consistent behavior across different devices and themes
• Rapidly iterate on components with hot reload support
• Seamlessly integrate UI testing into existing Flutter projects

An example use case for an app screen.

By implementing this structured approach to component management, teams eliminate the need for ad-hoc testing and screenshot sharing, significantly enhancing development efficiency and team collaboration.

What is Widgetbook Cloud?

Widgetbook Cloud streamlines UI component development through a collaborative platform. Key features include:

• Real-time team collaboration for instant component review
• Automated visual regression testing to detect UI changes
• Component version control with rollback capabilities
• Efficient review workflow with comments and approvals

The platform accelerates the design-to-development cycle by enabling direct component interaction in a dedicated environment.

Built-in automated testing maintains UI consistency while reducing manual QA effort, allowing teams to prioritize innovation.

Widgetbook Cloud Review feature

Strategies

Design systems consist of core components that serve as building blocks for complex components and screens. While Widgetbook offers the most value with 100% component coverage, sprint time constraints often limit implementation capacity. To maximize Widgetbook’s benefits during the migration phase, consider the following approaches based on your goals.

Core Components

When redesigning core components, Widgetbook excels at tracking changes and improving team communication. This approach maintains team alignment and prevents regressions across your application. Since core components are frequently reused, prioritize cataloging them first. This strategy maximizes the benefits for your team by establishing a solid foundation for component management.

New Components

When expanding your application’s feature set, new components are naturally introduced. These features and components typically undergo multiple iterations, making them ideal candidates for Widgetbook integration. This ensures design consistency and implementation accuracy throughout the process of optimizing your solution to meet customer requirements.

The two approaches can be mixed depending on your goals while migrating all your components to Widgetbook.

Widgetbook Entries Generator

Our partner LeanCode, a leading Flutter development agency, specializing in enterprise applications, has developed an automation tool that streamlines the integration of existing widgets into Widgetbook. This Widgetbook Entries Generator efficiently scans your codebase and generates the necessary Widgetbook code, significantly reducing manual implementation effort.

During their extensive work on Flutter projects, LeanCode identified a critical challenge: manually creating use cases for existing widgets was time-intensive and prone to errors. Drawing from their experience, they developed the Widgetbook Entry Generator to optimize the migration process.

Key benefits of the entries generator include:

• Automated generation of boilerplate code for rapid widget integration
• Enhanced accuracy through automated processing
• Streamlined adoption of Widgetbook’s testing and collaboration features

Widgetbook entries generator is available for VS Code.

Example project

Let’s explore the widgetbook-explained repository, which contains a simple grocery shopping app, as our example project.

The project structure is as following

.
├── lib      ⬅️ groceries_app
│   ├── app.dart
│   ├── features
│   ├── ... (omitted folders and files)
│   └── ui
│       ├── ui.dart
│       └── widgets
│           ├── app_bar.dart
│           ├── bottom_navigation_bar.dart
│           ├── card.dart
│           ├── counter.dart
│           ├── divider.dart
│           ├── empty_state.dart
│           ├── icon.dart
│           ├── icon_button.dart
│           ├── navigation_item.dart
│           ├── page_shell.dart
│           ├── primary_button.dart
│           ├── responsive_layout.dart
│           └── widgets.dart
├── pubspec.yaml
└── widgetbook      ⬅️ widgetbook_workspace
    ├── README.md
    ├── analysis_options.yaml
    ├── lib
    └── pubspec.yaml

Settings

Before the generator can be used, make sure to configure the settings of the extension.

Barrel File import

.
├── lib      ⬅️ groceries_app
│   ├── app.dart
│   ├── features
│   ├── ... (omitted folders and files)
│   └── ui
│       ├── ui.dart     🔥 Barrel file import
│       └── widgets
│           ├── (ommited files)
│           └── widgets.dart
├── pubspec.yaml
└── widgetbook      ⬅️ widgetbook_workspace
    ├── README.md
    ├── analysis_options.yaml
    ├── lib
    └── pubspec.yaml

Due to the file structure, we configure the Barrel File import as package:groceries_app/ui/ui.dart, which exports all Widgets from the production app.

Root directory name

After cloning the repository widgetbook-explained, we set the Root directory name to match widgetbook-explained.

Widgets directory path

This setting specifies the generation target for Widgetbook files.

.
├── lib      ⬅️ groceries_app
│   └── ... (omitted folders and files)
├── pubspec.yaml
└── widgetbook      ⬅️ widgetbook_workspace
    ├── README.md
    ├── analysis_options.yaml
    ├── lib     🔥 Where we want the generated files
    └── pubspec.yaml

We set the path to /widgetbook/lib to generate files in the ./widgetbook/lib directory.

How to genenerate a use-case for a Widget?

To generate a Widgetbook entry, open the PrimaryButton file, access the Quick Fix menu, and select "Create widgetbook entry for this widget".

Widgetbook entry generator creates the following code

import 'package:flutter/widgets.dart';
import 'package:groceries_app/ui/ui.dart';
import 'package:widgetbook/widgetbook.dart';
import 'package:widgetbook_annotation/widgetbook_annotation.dart' as widgetbook;

@widgetbook.UseCase(
  name: 'default',
  type: PrimaryButton,
)
Widget useCasePrimaryButton(BuildContext context) {
  return PrimaryButton(
    content: context.knobs.string(label: 'Content', initialValue: 'Content'),
    leading: const SizedBox.shrink(),
    trailing: const SizedBox.shrink(),
  );
}

The generated code is a functional Widgetbook use-case that serves as a starting point for further customization.

Developers can enhance the use-case by adding specific implementations, such as customizing the leading and trailing properties with icons.

Generate use-cases for multiple Widgets

Besides generating use-cases for individual widgets, the Widgetbook entry generator can create use-cases for an entire folder at once.

To use this feature, simply right-click on a folder in the file explorer and select the generate option.

Which will result in the following 20 generated files for Widgetbook.

.
├── lib      ⬅️ groceries_app
│   └── ... (omitted folders and files)
├── pubspec.yaml
└── widgetbook
    ├── lib     🔥 Generated files are located here
    │   ├── about
    │   │   └── about_screen.dart
    │   ├── app_bar.dart
    │   ├── app_theme.dart
    │   ├── bottom_navigation_bar.dart
    │   ├── card.dart
    │   ├── counter.dart
    │   ├── divider.dart
    │   ├── empty_state.dart
    │   ├── features
    │   │   ├── basket
    │   │   │   ├── views
    │   │   │   │   └── basket_view.dart
    │   │   │   └── widgets
    │   │   │       ├── basket_card.dart
    │   │   │       ├── cost_item_row.dart
    │   │   │       └── summary.dart
    │   │   └── utility
    │   │       └── placeholder.dart
    │   ├── icon.dart
    │   ├── icon_button.dart
    │   ├── main.dart
    │   ├── main.directories.g.dart
    │   ├── navigation_item.dart
    │   ├── page_shell.dart
    │   └── primary_button.dart
    └── pubspec.yaml

Of the 20 generated files 6 showed missing data for properties of type IconData which were fixed within a minute.

Conclusion

The Widgetbook entries generator significantly accelerates the integration of existing Flutter widgets into Widgetbook. By automating the creation of use-cases, teams can quickly build a comprehensive widget catalog without disrupting their development workflow. This tool, combined with Widgetbook’s testing capabilities, enables teams to maintain high-quality component libraries while focusing on delivering value to their customers.

Whether you choose to migrate core components, new features, or use the automated generator, Widgetbook provides the flexibility to adopt a testing strategy that fits your team’s needs. This structured approach to widget management ensures consistent design implementation and efficient team collaboration throughout your project’s lifecycle.