You have your Storybook project ready, and hosted at GitHub, great! Now you want to publish it so that everyone can view it online. Let's see how we can leverage GitHub's built-in features to host the static web app and automate the deployment process.
Enable GitHub Pages
First, we have to create a docs
folder at the root of our repository which will be used to host the published Storybook files.
Then we have to enable the GitHub Pages hosting feature and configure it to serve the static files from the docs
folder in our repository. Navigate to your GitHub repository settings and find the GitHub Pages section. Select the main
branch, then the docs
folder and, click Save.
Note: GitHub Pages needs our repository's visibility to be set to Public.
Set up the Storybook build script
Before we can deploy our Storybook project to GitHub Pages, we must first edit the build-storybook
script entry inside our package.json
file. This command will generate our project files. Open the package.json
file and edit the "build-storybook" entry as follows:
"build-storybook": "build-storybook -o docs-build"
This will tell Storybook to put the statically generated files into a docs-build
folder. We don't actually need to create a docs-build
folder in our repo as it will only be used temporarily for the deployment.
Note: If you have any static assets that you want Storybook to include in your build, you can do so with the
-s
switch followed by the static assets folder path. For example:
"build-storybook": "build-storybook -o docs-build -s ./stories/assets"
Set up the GitHub Actions workflow script
Github Actions is a fully integrated software development lifecycle workflow feature that enables us to create custom CI/CD processes directly integrated with our GitHub repository.
It's not in the scope of this post to go into detail about how GitHub workflow scripts work, there's great documentation available and plenty of tutorials around the net.
We're going to use GitHub Actions to automatically build and deploy our Storybook files. The action will trigger every time someone pushes a new commit into our main
branch of our repository that contains changes made to our stories
and src/components
folders.
We'll first create a YAML file to define our workflow configuration. Create a storybook.yml
file inside your repository in the following path
/.github/workflows/
Fortunately, there are many ready-made actions by the community, we are going to use the GitHub Pages Deploy Action action example script, slightly finetuned to suit our needs.
Put the following code into the /.github/workflows/storybook.yml
file we created earlier.
storybook.yml
name: Build and Deploy
on:
push:
paths: ["stories/**", "src/components/**"] # Trigger the action only when files change in the folders defined here
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout ποΈ
uses: actions/checkout@v2.3.1
with:
persist-credentials: false
- name: Install and Build π§
run: | # Install npm packages and build the Storybook files
npm install
npm run build-storybook
- name: Deploy π
uses: JamesIves/github-pages-deploy-action@3.6.2
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BRANCH: main # The branch the action should deploy to.
FOLDER: docs-build # The folder that the build-storybook script generates files.
CLEAN: true # Automatically remove deleted files from the deploy branch
TARGET_FOLDER: docs # The folder that we serve our Storybook files from
The key things to note here are:
- We are triggering the workflow only when files change inside the
stories
andsrc/components
folders. You can customize the script accordingly if your stories and/or source files reside in another folder. Alternatively, you can trigger the workflow on every push by setting theon
section to:
on: [push]
- We've set the
FOLDER
Key todocs-build
which is the folder we defined into ourpackage.json
"build-storybook" command. - We've added the
TARGET_FOLDER
Key and set it todocs
, which is the folder that our Storybook project is served from.
Next, commit the storybook.yml
file along with the package.json
into your repository and push it to GitHub.
Publish files
The final step is to make a change in our Storybook stories files then push a commit into our repository in order to trigger the storybook.yml
workflow. We can monitor the workflow progress by going into the Actions tab on the GitHub website.
If everything went well, the workflow should complete successfully, and a new commit with the published Storybook files inside the docs
folder will be created and pushed in our repository.
That's it! Storybook is now published automatically with GitHub actions and served with GitHub pages at https://<username>.github.io/<project-name>
| Thanks for reading!
Top comments (4)
The storybook convention is to put stories in
src/stories
, notstories
. You may want to update / mention that.Is there an updated version of this? Or did I miss a step? The action runs successfully, but the
/docs
is empty and nothing shows on my page.when clicking on another component, view doesn't change. it's stuck on the first one...
are you experiencing the same bug as me ? : citizenlabdotco.github.io/cl2-comp...
fixed :
github.com/storybookjs/storybook/i...
build-storybook --no-dll