Creating a Staging Environment for Teachable’s Design System
Using Github Actions and S3 to create a staging build of a design system’s Storybook and commenting that URL on the PR
👋 I’m Kristin Moser, Senior Software Engineer at Teachable. I’m also an avid user of and occasional contributor to Teachable’s Design System, Uni. Design systems are the product of strong collaboration between Design and Engineering. One way we’ve found to better help communication between the two functions is a staging environment.
Let’s say your team wants to make changes to a button component which exists as a standalone component, but is also used in forms, empty states, and banner components. You make the changes and push up a PR. Instead of sending screenshots or hopping on a Zoom call to see what your designer thinks of the changes, what if you could send them a URL? They could check out on their own machine how the changes affect the different uses of that button. If applications can have staging environments, why not design system docs?
Teachable uses Storybook to document our design system. Storybook makes building, organizing, and deploying a component library much easier. If you haven’t checked out the previous article in this series by Mike Kitzman on documenting a design system, you can read that here. Although you could do the following with any statically built site, I’ll be focusing on Storybook and our use case.
Teachable’s frontend exists in a mono-repo which contains several packages, including Uni. We also have a few other packages that use Storybook which you can read more about next in Nate Kidwell’s article! For the purposes of this post, we’ll assume we want to see a staging URL for two storybooks, one contained in the package uni and one in the student-checkout package.
Build
Using matrices to run this action for specific packages only, we first run a prepare script, which will install dependencies, restore cache, and run yarn prepare. The cache-key here will ensure that we are caching dependencies if no new packages are installed.
We then build each storybook using Nx (this may vary depending on your build setup) and move the build output to its own directory. Next, using Github’s built-in action, we upload the build output as an pipeline artifact so we can push it to S3 later.
Deploy
The next step in the workflow is to deploy the builds to S3. We’ll find the branch name and use it to form the folder name in S3.
Next, using Github’s built-in action, we’ll download those builds that we previously uploaded.
You’ll then need to set up your S3 credentials. AWS has actions that you can easily use to set credentials (check out this article for how that works).
Finally, upload to S3. Notice how the branch and project name are used to create the folders. This will be important when we later want to retrieve that URL.
Comment
After finding the branch name, we’ll use a pre-existing action to add a comment to the PR. Since we set our build folders in S3 to be the branch name, we’re able to access the index file directly. You can set up your own domain somewhere like Cloudfront.
Seeing it in action
I recently made a change to create a variant of a component in Uni. Since I’m not on the Design Systems team and this change was going to affect all consumers, it was best to get a sign off from the lead designer. Thankfully, I could easily send them a staging link and they were able to check it out themselves (Slack message for receipts 😉)!
