Deploy Storybook to GitHub Pages

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 and src/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 the on section to:

on: [push]

• We've set the FOLDER Key to docs-build which is the folder we defined into our package.json "build-storybook" command.
• We've added the TARGET_FOLDER Key and set it to docs, 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!

Comments

[Matthias]

The storybook convention is to put stories in src/stories, not stories. You may want to update / mention that.

[ben-rinehart]

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.

[DraganCL]

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...

[DraganCL]

fixed :
github.com/storybookjs/storybook/i...
build-storybook --no-dll