Widgetbook Cloud Review

Widgetbook Cloud introduces a Review feature, that empowers Flutter teams to compare changes in the user interface. Drawing inspiration from Pull Request reviews, this feature allows a streamlined analysis of UI changes.

Understanding Reviews#

A Widgetbook Review lets teams contrast UI changes between two versions. Moreover, it enables comparison of the current Widget version against its Figma design.

  • In a standard Pull Request, code differences between a base (previous version) and a feature (new version) branch are evaluated.
  • Similarly, in a Widgetbook Review, visual differences between the base build (last version) and feature build (current version) are assessed. For every pull request in your Git provider, our integration initiates a Widgetbook Cloud review. To facilitate this visual comparison, Widgetbook Cloud necessitates uploaded builds for both base and feature branches.

Review Statuses#

Different statuses can be assigned to the reviews:

  • Open: Awaiting assessment.
  • Merged: Linked with merged PRs, thus considered merged.
  • Closed: Associated with closed PRs, hence viewed as closed.
  • Updating: Missing crucial information for an open classification. A review qualifies as open if:
    • A head build is accessible, AND
    • A base build is available or at least one use-case is tied with a DesignLink.

Once a review's changes are approved, the developer closes the Pull-Request, updating the review status to merged.


To harness the Widgetbook Cloud Review feature, ensure your setup aligns with the following prerequisites:

How to add a Figma design link#

To add a Figma design link, you need to provide the designLink property to a use case:

  1. Got to Figma
  2. Go to the component that resembles your Widget
  3. Right-mouse click on the component
  4. Select Copy/Paste as > Copy Link
  5. Set the designLink property of the @UseCase annotation by pasting the copied link
  6. Let the re-run build_runner
  7. Commit the changes to Git
// Example from https://github.com/widgetbook/groceries-demo/blob/chore/design-link-for-appbar/lib/core/app_bar.dart
  designLink: 'https://www.figma.com/file/EXuEpwiyksLAejYX1qr1v4/Fluttercon-Berlin-2023-Demo?type=design&node-id=277-3056&mode=design&t=nVL8hLmc1jlcilZL-4',
  name: 'Default',
  type: AppBar

Publishing a Review#

The review feature works best if a build for the base branch and a build for the feature branch is available. In addition to uploading a feature branch, information about what has changed is important. To add this information, you can use the --base-branch argument of the CLI: widgetbook publish --api-key KEY --base-branch BASE-BRANCH.

Most CI/CD providers expose the BASE-BRANCH via environment variables for pull-requests. Check our CI/CD Setup guide for more insights.


# Install dependencies
flutter pub get
# !!! 
# !!! Run the build runner
# !!! This is mandatory even if you have commited the generated files since 
# !!! the generator creates files that are consumed by the Widgetbook CLI
# !!!
flutter pub run build_runner build --delete-conflicting-outputs
# Build the Widgetbook
flutter build web -t lib/ui_catalogs.widgetbook.dart
# Install the CLI
dart pub global activate widgetbook_cli
# Run the CLI
widgetbook publish --api-key API-KEY --base-branch main

Review Information#

To populate a review, information regarding the changes in use cases is mandatory. When the --base-branch argument is used, the CLI fetches details about the altered use cases.

Widgetbook Cloud showcases Reviews for all pull requests. But, only those Reviews with use case alterations are accessible.

At present, Widgetbook Cloud exclusively displays use cases that underwent changes, additions, or removals within the feature branch compared to the base branch. Consequently, existing use cases, even if unreviewed, won't be displayed.