A sound design component library can accelerate a team’s development. It aligns everyone with a common design language and uses reusable components. In Flutter, you can create a component library using Widgetbook.
Widgetbook has been a great tool so far for my team in ensuring we consistently build and ship UIs by maximizing the reusability of each component. Widgetbook also serves as a living document of around 70% to 80% of our projects’ widgets—this lead to speeding up engineering onboarding by up to 2x.
Your browser does not support the video tag.
Before everything else:
- Fork this repo with a Widgetbook example and checkout the branch
start-hereor; - You can also use your projects—make sure to follow along.
Let’s get started!
Widgetbook — the Storybook for Flutter
Widgetbook is an open-source tool for creating a component library for your Flutter widgets—it’s the missing Storybook for Flutter. Widgetbook helps you organize Flutter widgets and improve team collaboration during development.
Widgetbook can run just like any other Flutter app. Often, I test Widgetbook on native desktops like macOS or the web.
Source: https://docs.widgetbook.io
To open the Widgetbook in macOS, run:
cd lakbay
flutter run -t lib/widgetbook/main.dart -d macos
Widgetbook Cloud (early access)
Widgetbook Cloud offers a lot more features than the open-source package. It includes features like improved collaboration and feedback, is well-integrated into your project workflows, and hosts your component library projects on the web.
Source: https://www.widgetbook.io/
You can submit a request and get early access features to Widgetbook Cloud here.
Widgetbook package vs. Widgetbook Cloud
We won’t use Widgetbook Cloud in this article. Instead, we will use the Widgetbook package from the pub repository, which is open-source on GitHub.
What is Firebase Preview Channels?
Firebase Preview Channels is a hosting service of Firebase that enables you to release different versions of your sites or projects. We will use this to deploy different “previews” of our Widgetbook component library to the web whenever a pull request is opened to change our components or story files.
Firebase Preview Channels hosting is currently in beta.
Your Firebase project can have a “live” site using the domain SITE_ID.web.app and SITE_ID.firebaseapp.com. You also can brand your sites by adding custom domains. On the other hand, Firebase Preview Channels are deployed on different “channels” or temporary URLs on top of your existing live site, which you can use to preview and share with your internal team or testers.
Firebase Hosting Infrastructure
Each preview channel URL is a new version of your component library and is deployed on SITE_ID--CHANNEL_ID-RANDOM_HASH.web.app temporary URLs. The default expiration for each URL is seven days.
Source: https://firebase.google.com/docs/hosting/manage-hosting-resources#hosting-infrastructure
Setup Firebase project
To setup Firebase Preview Channels, you need to create a new project in the Firebase console:
We don’t need to add any projects just yet. We’re only going to use the Hosting service from Firebase.
Setup Firebase Service Account secret
We will use Firebase Service Account to identify and upload our apps to Firebase via GitHub Actions.
Let’s create Firebase Service Account using Firebase CLI.
First, login your Firebase account in the CLI:
firebase login
Next, initialize Firebase hosting in your project:
firebase init hosting
Modify the firebase.json and change the "public" path to "build/web".
{
"hosting": {
"public": "build/web",
"ignore": [
"firebase.json",
"**/.*",
"**/node_modules/**"
],
"rewrites": [
{
"source": "**",
"destination": "/index.html"
}
]
}
}
Finally, create a service account and upload it as an encrypted secret in GitHub Actions:
firebase init hosting:github
This will create a file firebase-hosting-pull-request.yml:
# This file was auto-generated by the Firebase CLI
# <https://github.com/firebase/firebase-tools>
name: Deploy to Firebase Hosting on PR
'on': pull_request
jobs:
build_and_preview:
if: '${{ github.event.pull_request.head.repo.full_name == github.repository }}'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: FirebaseExtended/action-hosting-deploy@v0
with:
repoToken: '${{ secrets.GITHUB_TOKEN }}'
firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_LAKBAY_F1B2E }}'
projectId: lakbay-f1b2e
That’s great! Now, we’re going to modify the workflow to upload our projects.
Setup GitHub Actions workflow
GitHub Actions is a continuous integration and continuous deployment (CD/CD) platform. GitHub Actions helps you automate your tests, builds, and releases to your users.
See the pricing page for the build limits. It’s free for open-source projects.
Setup workflow
We will build our component library for the web in this workflow.
First, modify the existing firebase-hosting-pull-request.yml file with the following:
name: Deploy to Firebase Hosting on PR
on:
pull_request:
branches:
- main
jobs:
build_and_preview:
if: '${{ github.event.pull_request.head.repo.full_name == github.repository }}'
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v3
- name: Cache Flutter
uses: actions/cache@v3
with:
path: /opt/hostedtoolcache/flutter
key: ${{runner.os}}-flutter
- name: Setup Flutter SDK
uses: subosito/flutter-action@v2
with:
flutter-version: '3.7.7'
channel: 'stable'
- name: Get dependencies
run: flutter pub get
- name: Build widgetbook
run: flutter build web --dart-define=widgetbook=true --release --web-renderer canvaskit --dart-define=BROWSER_IMAGE_DECODING_ENABLED=false
- uses: FirebaseExtended/action-hosting-deploy@v0
with:
repoToken: '${{ secrets.GITHUB_TOKEN }}'
firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_LAKBAY_F1B2E }}'
projectId: lakbay-f1b2e
env:
FIREBASE_CLI_PREVIEWS: hostingchannels
Next, let’s update our workflow permissions to upload our PR changes to Firebase Hosting.
Go to your project’s Settings, then under Code and Automation, select General.
Settings: https://github.com///settings/actions
Now, make any design changes and submit a pull request for review and let’s see if the workflow works!
You should see the comment posted by the GitHub Actions bot. It contains a URL to preview your component library hosted in Firebase!
Open the URL in your browser:
Example Preview Channel URL
Amazing! You’re almost done.
The generated preview channel URL expires in 7 days. You can change it by adding expires: <days:
- uses: FirebaseExtended/action-hosting-deploy@v0
with:
repoToken: '${{ secrets.GITHUB_TOKEN }}'
firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_LAKBAY_F1B2E }}'
projectId: lakbay-f1b2e
# Add this
expires: 3d
env:
FIREBASE_CLI_PREVIEWS: hostingchannels
Bonus
You don’t need to build a new version of your component library if you haven’t changed the component library or relevant story files. This will incur unnecessary billing overtime for the versions you don’t need to build.
What you can do is filter the files to trigger your GitHub Actions workflow:
name: Deploy to Firebase Hosting on PR
on:
pull_request:
branches:
- main
# Run the workflow when changes belong to these paths
paths:
- 'lib/components/**/*.dart'
- 'lib/**/*.story.dart'
That’s great! Now, you can see that the GitHub Actions will only run if you make any changes to the “paths” you specified above.
Final Thoughts
Using a design component library like Widgetbook can benefit your team. Automatically deploying previews of design changes to your component library will make design or code reviews more effective because you can see actual changes previewed on the web.
See you on the next one!