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.
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.
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
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:
- Got to Figma
- Go to the component that resembles your Widget
- Right-mouse click on the component
- Set the
designLinkproperty of the
@UseCaseannotation by pasting the copied link
- Let the re-run
- 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.
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
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.