Widgetbook 3: Migration Guide

It has been almost a year since our last stable release (v2.4.1). Today, we are happy to announce a NEW. STABLE. RELEASE. 🎉

We completely rethought Widgetbook from the ground up. This release is focused on creating a solid base that we can build more features onto, with Widgetbook Cloud in mind.

Highlights#

Addons: allows tweaking use-cases. They are like knobs but global.
Better Knobs naming convention.
Remove code generation, except for use-cases.
Remove all builders (e.g. deviceFrameBuilder), except appBuilder.
Almost zero-dependencies, after removing dependency on provider, go_router, flutter_bloc and freezed.

How to Migrate#

Annotations#

This release comes with code generation support for use cases only. So the following changes were made:

@WidgetbookUseCase has been renamed to @UseCase.
@WidgetbookApp has been replaced with @App that takes no parameters. The new @App annotation generates a file containing a single variable called directories.

Parameter Alternative
name None
foldersExpanded None
widgetsExpanded None
constructor None
devices DeviceFrameAddon
frames DeviceFrameAddon
themeType ThemeAddon
Removed Annotations

Annotation Alternative
@WidgetbookLocales LocalizationAddon
@WidgetbookLocalizationDelegates LocalizationAddon
@WidgetbookTheme ThemeAddon
@WidgetbookAppBuilder Widgetbook's appBuilder parameter

Parameter	Alternative
`name`	None
`foldersExpanded`	None
`widgetsExpanded`	None
`constructor`	None
`devices`	`DeviceFrameAddon`
`frames`	`DeviceFrameAddon`
`themeType`	`ThemeAddon`

Annotation	Alternative
`@WidgetbookLocales`	`LocalizationAddon`
`@WidgetbookLocalizationDelegates`	`LocalizationAddon`
`@WidgetbookTheme`	`ThemeAddon`
`@WidgetbookAppBuilder`	`Widgetbook`'s `appBuilder` parameter

Widgetbook Constructor#

The following parameters were removed or renamed:

Parameter	Alternative
`appInfo`	None
`useCaseBuilder`	None
`categories`	`directories`
`supportedLocales`, `localizationsDelegates` ,`localizationBuilder`	`LocalizationAddon`
`themes` ,`themeBuilder`	`ThemeAddon`
`textScaleFactors`	`TextScaleAddon`
`devices`, `deviceFrameBuilder`, `scaffoldBuilder`	`DeviceFrameAddon`

Knobs#

Some knobs have been renamed:

Old Name	New Name
`slider`	`double.slider`
`nullableSlider`	`doubleOrNull.slider`
`number`	`double.input`
`nullableNumber`	`doubleOrNull.input`
`text`	`string`
`nullableText`	`stringOrNull`
`options`	`list`
`nullableBoolean`	`booleanOrNull`

Catalogs#

WidgetbookCategory and WidgetbookFolder got their folders and widget properties refactor to a children property that can contain any structuring tree element.

Widgetbook.material(
  categories: [
    WidgetbookCategory(
      name: 'Category',
      folders: [
        WidgetbookFolder(
          name: 'widgets',
          widgets: [
            WidgetbookComponent(
              name: '$Container',
              useCases: [ ... ]
            )
          ]
        )
      ]
    )
  ],
  ...
)

Widgetbook.material(
  directories: [
    WidgetbookCategory(
      name: 'Category',
      children: [
        WidgetbookFolder(
          name: 'widgets',
          children: [
            WidgetbookComponent(
              name: '$Container',
              useCases: [ ... ]
            )
          ]
        )
      ]
    )
  ],
  ...
)