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 to your GitLab's CI/CD Variables. You can find the API key in the Widgetbook Cloud's project settings page. Make sure you uncheck "Protect variable" checkbox, to allow the variable to be accessible from feature branches.

Create a new GitLab pipeline file in your repository under .gitlab-ci.yml with the following content:

image: ghcr.io/cirruslabs/flutter

stages:
  - widgetbook

widgetbook_cloud_hosting:
  stage: widgetbook
  script:
    # Bootstrap App
    - flutter pub get
    - flutter gen-l10n
    # Bootstrap Widgetbook
    - cd widgetbook
    - flutter pub get
    - dart run build_runner build -d
    - flutter build web
    # Upload to Widgetbook Cloud
    - dart pub global activate widgetbook_cli
    - export PATH="$PATH":"$HOME/.pub-cache/bin"
    - widgetbook cloud build push --api-key "$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

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

Add the following workflow to your azure-pipeline.yaml file.

trigger:
  branches:
    include:
      - "*"

pr:
  branches:
    include:
      - "*"

stages:
  - stage: WidgetbookHostingStage
    displayName: Hosting
    jobs:
      - job: HostingJob
        displayName: Hosting
        pool:
          vmImage: "ubuntu-latest"
        steps:
          - task: FlutterInstall@0
            displayName: "Install Flutter SDK"
            inputs:
              mode: "auto"
              channel: "stable"
              version: "latest"

          - task: Bash@3
            displayName: "Bootstrap App"
            inputs:
              targetType: "inline"
              script: |
                $(FlutterToolPath)/flutter pub get
                # Add any other steps needed to make your
                # app widgets available for Widgetbook

          - task: Bash@3
            displayName: "Build Widgetbook"
            inputs:
              workingDirectory: "widgetbook"
              targetType: "inline"
              script: |
                $(FlutterToolPath)/flutter pub get
                $(DartToolPath)/dart run build_runner build -d
                $(FlutterToolPath)/flutter build web -t lib/main.dart

          - task: Bash@3
            displayName: "Install Widgetbook CLI"
            inputs:
              targetType: "inline"
              script: |
                $(DartToolPath)/dart pub global activate widgetbook_cli

          - task: Bash@3
            displayName: "Push Widgetbook Build"
            inputs:
              workingDirectory: "widgetbook"
              targetType: "inline"
              script: |
                $HOME/.pub-cache/bin/widgetbook cloud build push --api-key $(WIDGETBOOK_API_KEY)

Overview

Guides

Addons

Knobs

Migration

Next

Cookbook