This article explains the open source Flutter package Widgetbook
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.
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.
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.
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:
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 :
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:
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.
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.
@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
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.
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! 💙