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.

Overview#

1. Understanding Reviews
2. Review Statuses
3. Requirements
4. Add a Figma design link
5. Publishing a review

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.

Requirements#

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

• Incorporate the widgetbook_generator package version 3.2.0. No additional configuration needed.
• Integrate the widgetbook package version 3.3.0. No extra setup required.
• Employ the CLI from widgetbook_cli package.
• Set up our GitHub app.

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
@UseCase(
  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.

Example#

# 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.