Widgetbook Cloud Hosting

When you create a new commit in Git, a new version of your code is created. With Widgetbook Builds developers make the new version of their local Widgetbook accessible for the whole team. If set up with CI/CD, you can have a build for each commit, for each pull-request and for each branch.

Pushing a new build#

To create a Widgetbook Build, follow these steps inside your Widgetbook project:

Run widgetbook_generator to generate metadata about your use-cases and components
dart run build_runner build -d

Build the Widgetbook for the web

# Default target (i.e. `lib/main.dart`)
flutter build web

# Custom target
flutter build web -t lib/main.widgetbook.dart

Install the Widgetbook CLI

dart pub global activate widgetbook_cli

Get your API key from the Widgetbook Cloud's project settings page.

Push the build to Widgetbook Cloud

widgetbook cloud build push --api-key PROJECT_API_KEY

The cloud push command uses the following directories:

build/web/ to create a .zip archive that will be uploaded to Widgetbook Cloud.
.dart_tool/build/generated/[your_app_name]/ to send metadata, about the generated use-cases, that will be used for Widgetbook Cloud Review.

Pushing new builds with CI#

To better integrate Widgetbook Cloud with your development workflow, it is recommended to use CI/CD to push a new build on every push of a new commit.

The following workflows assume you have Widgetbook structured as a sub-package

your_app/
├── pubsepc.yaml
├── lib/
└── widgetbook/
    ├── pubsepc.yaml
    └── lib/

Add WIDGETBOOK_API_KEY to your GitHub repository's secrets. You can find the API key in the Widgetbook Cloud's project settings page.

Create a new GitHub Actions workflow file in your repository under .github/workflows/widgetbook-cloud-hosting.yml with the following content:

name: Widgetbook Cloud Hosting
on: push

jobs:
  widgetbook-cloud-hosting:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup flutter
        uses: subosito/flutter-action@v2
        with:
          channel: stable

      - name: Bootstrap App
        run: |
          flutter pub get
          # Add any other steps needed to make your
          # app widgets available for Widgetbook

      - name: Build Widgetbook
        working-directory: widgetbook
        run: |
          flutter pub get
          dart run build_runner build -d
          flutter build web -t lib/main.dart

      - name: Install Widgetbook CLI
        run: dart pub global activate widgetbook_cli

      - name: Push Widgetbook Build
        working-directory: widgetbook
        run: widgetbook cloud build push --api-key ${{ secrets.WIDGETBOOK_API_KEY }}

Add WIDGETBOOK_API_KEY under widgetbook_credentials group in your Codemagic project's environment variables. You can find the API key in the Widgetbook Cloud's project settings page.

Add the following workflow to your Codemagic codemagic.yaml file.

workflows:
  widgetbook-cloud-hosting:
    name: Widgetbook Cloud Hosting

    triggering:
      events:
        - push

    environment:
      flutter: stable
      groups:
        - widgetbook_credentials

    scripts:
      - name: Bootstrap App
        script: |
          flutter pub get
          # Add any other steps needed to make your
          # app widgets available for Widgetbook

      - name: Build Widgetbook
        working_directory: widgetbook
        script: |
          flutter pub get
          dart run build_runner build -d
          flutter build web -t lib/main.dart

      - name: Install Widgetbook CLI
        script: dart pub global activate widgetbook_cli

      - name: Push Widgetbook Build
        working_directory: widgetbook
        script: widgetbook cloud build push --api-key $WIDGETBOOK_API_KEY