Storybook tutorial: deploy to GitHub pages

If you don’t have an existing Storybook setup, you can start by cloning my pre-configured Storybook boilerplate that includes Tailwind and ShadCN. This will allow you to quickly get started without setting up Storybook from scratch.

1. Clone the Boilerplate (Optional)

git clone https://github.com/nima70/tailwind-shadcn-storybook-boilerplate.git
cd tailwind-shadcn-storybook-boilerplate

Note: If you’re using an existing project, you can skip this step. However, if you’re cloning from my repo, you’ll need to remove the .git folder to disconnect it from my repository and create your own Git history:

rm -Recurse -Force .git
rm .github

2. Open the Project in VSCode

Once you’ve prepared the boilerplate or your existing project, open it in VSCode using the following command:

code .

3. Update the package.json

Now, open package.json and make sure to add or update the following lines:

"homepage": "./",
"scripts": {
  "build-storybook": "storybook build -o ./docs"
},

Your package.json should look like this at the end:

{
  "name": "tailwind-shadcn-storybook-boilerplate",
  "version": "1.0.0",
  "main": "index.js",
  "homepage": "./",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build -o ./docs",
    "build": "webpack --config webpack.config.js"
  }
}

This configuration ensures that Storybook will build the static files into the ./docs folder, which is required for GitHub Pages to serve the site.

4. Install Dependencies and Build Storybook

Next, run the following commands to install the project’s dependencies and build the Storybook files. We are using the --force flag with npm install to ensure any dependency conflicts are resolved automatically.

npm i --force
npm run build-storybook

Check the contents of the docs folder to verify that the build was successful:

ls docs

You should see output similar to this:

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----         9/27/2024   4:56 PM                sb-addons
d-----         9/27/2024   4:56 PM                sb-common-assets
d-----         9/27/2024   4:56 PM                sb-manager
d-----         9/27/2024   4:56 PM                sb-preview
d-----         9/27/2024   4:56 PM                static
-a----         9/27/2024   4:56 PM          37263 270.2a919bf8.iframe.bundle.js
-a----         9/27/2024   4:56 PM         145713 448.70ada959.iframe.bundle.js
-a----         9/27/2024   4:56 PM            971 448.70ada959.iframe.bundle.js.LICENSE.txt
-a----         9/27/2024   4:50 PM              2 asset.txt
-a----         9/27/2024   4:56 PM           2870 components-button-stories.a9dc1e4c.iframe.bundle.js
-a----         9/27/2024   4:50 PM           1251 favicon.svg
-a----         9/27/2024   4:56 PM          15660 iframe.html
-a----         9/27/2024   4:56 PM           2871 index.html
-a----         9/27/2024   4:56 PM            264 index.json
-a----         9/27/2024   4:56 PM           5595 main.e6d20a1d.iframe.bundle.js
-a----         9/27/2024   4:50 PM          49460 nunito-sans-bold-italic.woff2
-a----         9/27/2024   4:50 PM          47144 nunito-sans-bold.woff2
-a----         9/27/2024   4:50 PM          49620 nunito-sans-italic.woff2
-a----         9/27/2024   4:50 PM          47072 nunito-sans-regular.woff2
-a----         9/27/2024   4:56 PM           1227 project.json
-a----         9/27/2024   4:56 PM           5247 runtime~main.7cc5a522.iframe.bundle.js

5. Create a New GitHub Repository

If you don’t already have a GitHub repository for this project, create an empty repository on GitHub and name it storybook-githubpages-deploy

Once the repository is created, initialize it locally and push your code:

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/your-username/storybook-githubpages-deploy.git
git branch -M main
git push -u origin main

6. Configure GitHub Pages

Now that your code is pushed to GitHub, it’s time to configure GitHub Pages to serve the Storybook site.

Open your GitHub repository and navigate to Settings > Pages.

Under Source, select the main branch and set the folder to /docs:

Click Save.

GitHub will now deploy the contents of the docs folder and serve it through GitHub Pages.

7. Verify the Deployment

After a few minutes, GitHub Pages should be live. You can verify this by visiting your GitHub Pages URL, which should look something like this:

https://your-username.github.io/storybook-githubpages-deploy/

You should see your Storybook site similar to this:

Troubleshooting

If you don’t see your site right away, give it a few minutes for GitHub Pages to process the deployment. You can also check the Actions tab in your repository to see the logs of your GitHub Actions workflow and verify if the deployment was successful.

Well done! You’ve successfully deployed your Storybook to GitHub Pages.