Deploy Storybook to GitHub Pages
Tags: vue, storybook, github
Published: 2020-10-11 07:37:18

You have your [Storybook](https://storybook.js.org/) project ready, and hosted at [GitHub](https://github.com/), 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.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/8hywlzvmdhy3kt9jgivi.png)

> 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:
```json
"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:
```json
"build-storybook": "build-storybook -o docs-build -s ./stories/assets"
```
## Set up the GitHub Actions workflow script
[Github Actions](https://docs.github.com/en/free-pro-team@latest/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](https://docs.github.com/en/free-pro-team@latest/actions) 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](https://github.com/marketplace?type=actions), we are going to use the [GitHub Pages Deploy Action](https://github.com/JamesIves/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
```yaml
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:
```YAML
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.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/i1f8ih2gtlzf9o4rewn0.png)

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!