How We Boosted Moving Flutter Widgets to Widgetbook

At LeanCode, we aim to simplify workflows and help teams focus on what matters most. While working on complex Flutter projects, we noticed that integrating widgets into Widgetbook was often repetitive and time-consuming.

To address this, we created the Widgetbook Entries Generator - a VSCode extension that simplifies the process. By automating the generation of widget use cases, it transforms a manual task into a quick and efficient step in your workflow.

What is Widgetbook?

Widgetbook is a Flutter-specific development and design tool that serves as a living documentation system for your widgets and UI components. It enables you to:

• Organize widgets into categories and subcategories for easy discovery.
• Preview widgets in real-time with different states, themes, and properties.
• Customize widget configurations by adjusting parameters dynamically through a built-in interface.
• Share previews of widgets with team members or stakeholders without requiring them to run the app locally.
  

Essentially, it provides a smooth way to develop, test, and showcase Flutter components in isolation, enhancing productivity and clarity.

Why do we use Widgetbook at LeanCode?

1. Improved collaboration between designers and developers

Designers can easily review widget implementations, experiment with configurations, and validate designs without needing to navigate the app or set up the development environment.

2. Efficient debugging and iteration

Since widgets can be previewed in isolation, bugs or design inconsistencies can be addressed faster without the need to navigate through the app's full UI structure.

3. Scalable app development

Widgetbook simplifies onboarding for new team members by providing a clear overview of available components and how they work.

Big projects with extensive design systems will find Widgetbook especially useful. Teams working on apps with complex UI structures or multiple themes can use it to centralize all reusable components. It ensures consistency and helps developers quickly find and understand how to use a specific widget.

You can learn more about Widgetbook on its website.

The problem with adding components to Widgetbook

Adding new use cases to Widgetbook can be tedious, especially when ensuring each widget constructor and property is configurable. For every widget, you need to define a use-case and, if you want this widget to be fully configurable in the Widgetbook app, translate its parameters into appropriate knobs (list, string, boolean, etc.), setting default values and options for dropdowns or nullable inputs.

For widgets like Button, this means creating knobs for properties like type, text, and enabled, aligning them with the correct data types. The process becomes repetitive, particularly for widgets with multiple constructors, as you repeat the same setup with minor variations. That is if you want to have a separate Widgetbook use case for each of them since they often represent different business use cases, too.

While the outcome — a fully dynamic widget preview — is valuable, the work itself is highly mechanical and often feels like a chore, involving repetitive coding that’s essential but rarely engaging.

How we simplified this process

To make adding new widgets to Widgetbook easier and more efficient while working on projects at LeanCode, we developed the Widgetbook Entries Generator extension for VSCode. This tool automates the process of adding use cases, addressing the repetitive and time-consuming nature of manually setting up Widgetbook entries.

The extension simplifies your workflow by analyzing a widget’s constructors and properties, automatically creating use cases for each constructor. For every property, it selects the most appropriate knob based on a predefined type-knob mapping. You can also customize these mappings or override the defaults to fit your project’s specific needs. If no suitable type-knob pair is found, the extension assumes the property is a custom enum and assigns a list knob by default.

With features like a Quick Fix option, you can generate a Widgetbook entry for any currently open widget in just a few clicks. Additionally, the batch processing feature allows you to create use cases for an entire directory of widgets.

Generating a use-case for a single widget:

Generating use-cases for multiple widgets:

How can existing design systems benefit from it?

As we've established before, for large design systems, Widgetbook provides a centralized way to document, preview, and test reusable UI components in isolation, making collaboration between developers and designers more efficient. It ensures consistency across projects by serving as a single source of truth for component behavior and design.

The Widgetbook Entries Generator extension can significantly simplify introducing Widgetbook into such systems, saving time and effort for development teams. For organizations already working with a large set of reusable widgets, manually creating Widgetbook use cases can be daunting and time-consuming.

The workflow for introducing Widgetbook into existing projects with the Widgetbook Generator extension can be as follows:

1. Batch generate use-cases for all existing widgets: Start by using the generate entry for each widget in the directory feature to automatically create use-cases for all widgets in the project. Note that batch generation for large directories, especially those with many nested subdirectories, is still in an experimental phase. For smoother operation, generating use cases for smaller directories is recommended rather than attempting this for the entire project at once. If any issues arise, you can always generate use cases for individual widgets one by one using the quick-fix option.

2. Add new widgets easily: When adding new widgets to your design system, simply use the quick-fix option and select the Generate Widgetbook entry for this widget choice. This will automatically create a new use case for the widget.

By following this workflow, teams can quickly establish a comprehensive Widgetbook for their design system.

How to use it?

1. Install the extension. Open VSCode, navigate to the Extensions view, and search for Widgetbook Generator. Click Install to add it to your editor. Alternatively, you can install it from the VSCode marketplace

2. Configure the extension. In IDE settings, set up the extension by providing some basic project details, such as the path to your Widgetbook directory, your project’s directory name, and the import path for your widgets barrel file (only if your project uses one, otherwise you can still import widgets manually after the code is generated). Additionally, configure properties like the generation approach (automatic or manual) and specify the path to a file containing custom knobs for your widgets if you want to use any. For detailed instructions, refer to the Configuration section of the README.

3. Generate use cases. Start generating use cases for your widgets, as demonstrated above. You can generate entries for individual widgets or entire directories. For a complete list of features and instructions, check out the Usage section of the README

4. Add generated use cases to the Widgetbook widget (directories property). You can now interact with them in the Widgetbook app.

How does it work?

1. The extension begins by scanning and parsing the selected Dart file to extract information about the widget's fields and constructors. Since Dart’s flexibility allows for various constructor styles, this parsing process is the most challenging and fragile. The extension has been tested with many scenarios to ensure robustness. However, users are encouraged to create an issue for further refinement for any edge cases that might still be missed.

2. Based on the parsed data and the extension’s configuration settings (defined by the user), the tool automatically generates Widgetbook-compatible component definitions and use cases. It maps widget properties to configurable knobs, allowing for dynamic adjustment of parameters within Widgetbook.

3. Finally, the extension generates a new file for the use-case code, naming and placing it according to the user's configuration and the widget’s name.

Summary

Widgetbook is a powerful tool for Flutter projects that allows you to document, preview, and test UI components in isolation. It enables teams to maintain design consistency and ensures that components behave as expected. By offering a single source of truth for UI components, Widgetbook makes collaboration between developers and designers more efficient, especially in large design systems.

However, manually creating use cases for each widget can be tedious. To address this, we developed the Widgetbook Entries Generator extension for VSCode, which automates the creation of use cases, saving time and effort. Whether you're already using Widgetbook in your project — or you're considering it but find the setup process overwhelming — this extension can significantly simplify the integration, making creating and managing use cases for your widgets faster and more efficient.

At the time of writing this article, the extension is still in the early stages of development. If you encounter any issues while using it, don't hesitate to open an issue in the extension's repository. The more projects we can test it with, the better we can make it.