Widgetbook — The Storybook for Flutter

This article explains the open source Flutter package Widgetbook. It is the Storybook for Flutter, which helps developers cataloguing their widgets, testing them quickly on different devices and themes, and sharing them easily with designers and clients.

What is a Storybook?

Every flutter developer coming from a web development background has probably heard and most likely even used Storybook.js before. It’s one of the most loved React packages, which speeds up UI development by allowing developers to build components in isolation. Developers can create stories, which represent specific use cases of a component. These stories can be catalogued. The resulting Storybook can be accessed by non-developers like designers or clients as well, which simplifies the review process. Since Flutter is based on widgets, we named our package Widgetbook.

How does Widgetbook compare to other Flutter Storybooks?

Even though there are already some Flutter packages available trying to provide the values of Storybook.js, they lack certain usability and maintainability features. The code to set up and maintain the Storybooks of all existing packages has to be written manually, which is time consuming and cumbersome. The only exception is Framy but this package has not been maintained since October 2020 and is thus not null safe. Furthermore, the UI of all Storybooks is difficult to use. Therefore, we created Widgetbook. In its latest release, it comes with annotations which simplify setting up and maintaining it via code generation. Widgetbook is the only maintained Storybook package for Flutter with annotations. Since our team of three successfully raised funding, we are able to dedicate all of our time and resources in improving and maintaining our open source package Widgetbook.

Use cases for Widgetbook

Build widgets in isolation and test them visually

Widgetbook provides an environment to build UIs in isolation. It allows you to develop widgets without distractions from the surrounding screen and dependencies. In the UI of Widgetbook, you can quickly preview and test your widgets visually on different devices and themes. It allows you to spot UI flaws while developing that would be tedious to test on an emulator:

‍

Keeping an overview of all your widgets

When your app grows and more and more developers are working on it, it becomes difficult to still keep track of all the widgets in your app. At this point, even the best naming conventions can not prevent developers questioning, if some widgets have already been developed or not. Often these confusing structures lead to chaos and developers building identical widgets multiple times.

By using widgetbook, you can quickly preview all your widgets and screens, as well as their relevant use cases :

Collaborate with designers, product owners and clients

The review process in app development teams is often tedious and inefficient. When the developer finished developing a critical part of the app, it mostly needs to be reviewed by a designer, product owner or client. To receive feedback, the developer mostly has three options:

1. Scheduling a meeting and present, as well as discuss, the latest changes during the meeting. It often takes some time until the reviewer is available and meetings are mostly inefficient.
2. Creating an executable including the latest changes and making it available for non-developers to download it on their smartphone. The reviewers now have to navigate through the entire app to find the part that was changed. Spotting edge case design errors in the running app is hardly feasible. Even when finding an error, it is now difficult for the reviewers to give precise feedback. Either the reviewer schedules a meeting with the developer, resulting in the same problem mentioned above, or they take screenshots of the flaws and send those to the developer in combination with further explanations via messaging tools, such as Slack. When the feedback was not precise enough, which often happens, they need to exchange more messages or schedule a meeting after all.
3. Taking screenshots of the relevant parts and sending them to the reviewers. However, screenshots often lack necessary information. Animations and small interactions, e.g. with buttons, enhance the user experience but cannot be displayed and reviewed in a screenshot.

By using our hosted Widgetbook service, your reviewers can easily access your Widgetbook via the web browser. Thereby, they can quickly review all of your widgets and screens on different devices and themes. Additional collaboration features simplify the review process even further. More information on our collaboration platform is provided at the end of the article.

How to use Widgetbook?

We provide detailed documentation on our pub.dev site. You have the choice, if you would like to set up and maintain your Widgetbook manually or if you would like to speed up the process with code generation via annotations. Using annotations requires you to use our widgetbook_annotation and widgetbook_generation package as well. Thereby, the structure of the Widgetbook will be generated for you. To keep this article focused and underline the differentiation to the other Flutter Storybooks, I’ll only focus on the approach with annotations.

Using annotations to easily setup and maintain your Widgetbook

@WidgetbookApp

The annotation @WidgetbookApp has to be set only once and is mandatory for the code generation process. It is not important which element is annotated, but the location of the file in which @WidgetbookApp is used, defines the folder in which widgetbook_generator will create the file app.widgetbook.main. The app.widgetbook.main file contains all the code to run the Widgetbook.

Parameters

The annotation @WidgetbookApp has one required parameter name and one optional parameter devices.

From the name parameter, the generator will create the AppInfo property of Widgetbook. Therefore, this value will show in the upper left corner of the Widgetbook.

From the devices parameter, the generator will create the devices in which one can preview the widgets.

Example

For the following app structure

one might add @WidgetbookApp to the App Widget defined in app.dart.

The package widgetbook_generator will then create a new file app.widgetbook.dart next to the app.dart file. The resulting app structure will look like this:

@WidgetbookUseCase

@WidgetbookUseCase allows developers to mark functions as a use case. The @WidgetbookUseCase must be applied to a function

or a lambda expression

Parameters

@WidgetbookUseCase requires the two parameters name and type.

The name parameter specifies how the use case will be displayed in the navigation panel in the Widgetbook.

The type parameter specifies to which type of Widget the use case belongs. From this information and the location of the file in which the annotation is used, widgetbook_generator will create the navigation panel shown on the left side of the Widgetbook.

Example

Lets assume that the file structure looks like this

A use case for AwesomeTile located in /lib/tiles/awesome_tile.dart can be defined in that file by implementing the following

It often happens that your widget is more complex. In such case, feel free to wrap the widget with whatever you need. This can also be a Provider, Bloc or other state management Widget.

After generating the code for the Widgetbook, you will find a navigation panel with the following content

If you require multiple use cases for a Widget, feel free to define multiple @WidgetbookUseCases per Widget. The additional use cases will be located in the navigation panel similar to the showcased use case.

@WidgetbookTheme

@WidgetbookTheme allows developers to annotate the light and dark theme of their app. Similar to @WidgetbookUseCase, @WidgetbookTheme is used on methods returning a ThemeData object.

Constructors

@WidgetbookTheme features two constructors @WidgetbookTheme.light() and @WidgetbookTheme.dark() for differentiation between the light and dark theme of the app.

Example

Collaboration with designers, product owners and clients

Currently, Widgetbook already allows developers to catalogue their widgets and test them quickly on different devices and themes. If you would like to share your Widgetbook with your design team or your clients, it is only somewhat feasible. You could run a web build and host it on your own server but that structure only supports working on one branch. Especially when working in bigger teams, multiple developers are working on different branches. Thus, the hosted Widgetbook should be shown in multiple versions. Also the current Widgetbook does not come with any collaboration features.

But no worries, we got you! We’re currently developing a collaboration platform that hosts your Widgetbook on a web server supporting different branches and collaboration features to simplify and accelerate review processes. We’re developing this platform in close collaboration with selected early users as part of our pilot customer program. If you would like to participate in our pilot customer program as well, sign up for it on our plans page. We only have limited seats available.

Questions, suggestions, feedback

For more information on Widgetbook, please follow us on Twitter and LinkedIn. If you want to get in touch with us join our Discord, text us on Twitter or LinkedIn, or send me a mail. We love to get feedback from our users! 💙

‍