Widgetbook 2.0 in Flutter: Crash Course in Code Generation Approach

A community contribution from Cavin Macwan 🎉

Disclaimer: This article is about Widgetbook 2.0 Parts of the content may be out of date.

Hi all

In the last part of the WidgetBook series, We covered various topics on WidgetBook such as the need for WidgetBook and the various functionalities which WidgetBook provides in Flutter. I also explained all the examples and use cases along with the code and the output.

Therefore, if you want to learn about the core concepts and functionalities of WidgetBook, then I recommend checking the first part:


In this part, we will cover how you can leverage code generation to generate all the boilerplate code for WidgetBook. So without further a do, let’s get started!

Table of Contents

1. Why Generator Approach over manual

In the last part, I used the manual approach to create all the use cases, categories and every other thing. But WidgetBook provides the code-generation packages that you can utilize to focus on the main app logic, rather than focusing on creating the WidgetBook tree.

These are some of the advantages of going with the generator approach:

  • Your time will be much reduced to create WidgetBook as the code generation will take care of those things.
  • It will create the tree structure automatically based on the file structure of your app.

Now let’s see how you can setup the WidgetBook to leverage code generation 😉

2. Setting Up

To setup WidgetBook with code generation, follow the steps below:

Step — 1 (Add the dependencies)

  • Add these dependencies to your pubspec.yaml file.
Dependencies for WidgetBook
  • Now let’s understand the package that we’ve added:
  1. widgetbook_annotation : This package will give you all the annotations that you can use to configure various WidgetBook functionalities
  2. widgetbook : This package doesn’t need any introduction 😉
  3. widgetbook_generator : This package is used for generating the boilerplate code. It works along with the build_runner package.

Now that you’ve added the dependencies, let’s go to the next step.

Step — 2 (Create a file) 📁

  • Inside your lib folder, create one file named ui_catalogs.dart . Your folder structure should look like this:
folder structure after adding ui_catalogs.dart file

Step — 3 (Add annotations) 🪧

  • Now, let’s add some code into ui_catalogs.dart

As you can see, we’ve just added one annotation (i.e @WidgetbookApp.material()) and below that, we’ve added one late variable.

That’s all the necessary code you need to write to generate your code!😲

Step — 3 (Run build runner)

Now run this magical command in your terminal to generate all the boilerplate code 🧬

After you run this command, it will take some time to generate the file. The file will be named as ui_catalogs.widgetbook.dart .

Now Let’s look into the code it generates:

Code generation for ui_catalogs.dart

In the manual approach, you would have to write all the code which is generated automatically. That’s why WidgetBook’s code generation is so efficient 💙

Step — 4 (Run the app) 🏃

  • Now that our code has been generated, let’s run the app. You should run this app either on Windows or MacOS because hot-reload is not supported on the web as of now.
  • To run the WidgetBook on Mac, you can use this command:

After you run the app, it will look something like this:

Notice that everything is pretty much empty here! Because we’ve not added the Use cases yet. Now let’s see how can we add use cases and manage the folder structure of the WidetBook.

3. UseCases and Folder Structure 📂

WidgetBook provides the annotation for generating the UseCases, so that you can directly annotate a widget with the @WidgetbookUseCase , and once you run the build runner command, it will automatically generate the UseCases code for you.

Let’s understand this by an example:

  • First, inside the lib folder, create one folder named pages . After that, create one file named home_page.dart . Your folder structure should look like this:
Folder Structure
  • Now, add this code🧑‍💻 in the home_page.dart:
  • Now, to add the UseCase, follow the steps below:
  • As you can see, We’ve created one function that returns the widget. And we’ve annotated that widget with the @WidgetbookUseCase . Let’s understand it.
  • @WidgetbookUseCase mainly takes 2 arguments: 1. Name of the UseCase and 2. Type of the UseCase
  • Now to generate the rest of the code, run the build runner command in the terminal:
  • Once you run this command, run your WidgetBook by the command down below:

  • If you see the output, it should look like the above one.
  • Did you notice the structure on the left side? It’s been generated automatically by WidgetBook!

Therefore, the navigation structure of the Widgetbook resembles the structure of your application or package.

4. Add-ons

If you want to know what Add-ons are and why it is used, you can check out my previous blog through this link.

In this blog, you’ll see how you can set up these Add-ons with the generator approach.

1. Theme Add-on

The Theme Add-on provides theming for previewing and changing your themes in WidgetBook. Thus, you can check and verify your themes in real time.

  • To use the MaterialThemeAddon with the widgetbook_generator package annotate a function that returns your ThemeData with the @WidgetbookTheme annotation.
  • Let’s see the example of MaterialThemeAddon :
Theme add-on
  • As you can see, you have to clarify the name of the theme, and whether the theme is default or not.
  • Now let’s see an example of CupertinoThemeAddon :
Cupertino Theme Add-on

2. Text Scale Add-on

As the name suggests, this Add-on allows you to change the text scale for previewing your use cases. By adding this, you can check if your layout is going to break or not when the scale of the text changes.

  • You can define the list of text scale factors inside the @WidgetbookApp.material like this:

3. Frame Add-on

As you can see in this GIF, this add-on provides you the ability to view and test all of your use cases on different scree-sizes along with the frames of those devices.

WidgetBook gives you a bunch of Android, iOS and Desktop devices that you can use directly. You can also create your own custom device if you want.

You can use this add-on like this:

Frame Add-on Example

You can also define your own devices by extending the Device like this:

If you want to try these examples on your own then you can check out my GitHub repository:


I hope you learned something new from this blog. If you didn’t understand any of this part or have any doubts, then you can ask me in the comments, or on my LinkedIn and Twitter.