LogoWidgetbook

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.

Concept of 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.

Publish a Review#

  1. Make sure to incorporate the widgetbook_generator package version 3.7.0.
  2. Integrate the widgetbook package version 3.7.0.
  3. Employ the CLI from widgetbook_cli package.
  4. Set up our GitHub app.
  5. Upload a build of your base branch, e.g. main. Using this command widgetbook publish --api-key <API>. See how to upload a build.
  6. Create a new branch for your changes, e.g. feat/awesome-feature.
  7. Add new or change existing Widgetbook use cases in your feature branch. Note: Without changed use cases, the review feature won't work, as there would be nothing to review.
  8. Optionally, add addons and knobs as well as Figma design links.
  9. Publish a review for the feature branch with changed Widgetbook use cases using this command: widgetbook publish --api-key <API> --base-branch main. This will publish both a build and a review for the latest commit in your feature branch.

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

Example#

# Install dependencies
flutter pub get
# !!! 
# !!! Run the build runner
# !!! This is mandatory even if you have committed 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.

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.

How to set up addons and knobs#

In order for the addons and knobs in your Widgetbook builds to work with our review feature, make sure you have the WidgetbookCloudIntegration added to the integrations array in your Widgetbook app:

@widgetbook.App()
class WidgetbookApp extends StatelessWidget {
  const WidgetbookApp({super.key});

  @override
  Widget build(BuildContext context) {
    return Widgetbook.material(
      // Use the generated directories variable
      directories: directories,
      addons: [],
      integrations: [
        // Important to send addons & knobs to Widgetbook Cloud
        WidgetbookCloudIntegration(),
      ],
    );
  }
}

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
)