Storybook Deployer

This is a simple tool allows you to deploy your Storybook into a static hosting service. (Currently, GitHub Pages and AWS S3 beta)

$ storybook-to-ghpages --help
$ storybook-to-aws-s3 --help

Options:
  --help, -h                      Show help.                                             [boolean]
  --version                       Show version number                                    [boolean]
  --existing-output-dir, -e       If you have previously built your storybook output (through a
                                  different CI step, etc) and just need to publish it     [string]
  --out, -o                       Configure the output directory                          [string]
  --packages, -p                  Directory for package.jsons (monorepo support)          [string]
  --monorepo-index-generator, -m  Path to file to customize the monorepo index.html. This function
                                  should return the html for the page.                    [string]
  --script, -s                    Specify the build script in your package.json           [string]
  --ci                            Deploy the storybook in CI mode (github only)          [boolean]
  --dry-run                       Run build but hold off on publishing                   [boolean]
  --remote                        Git remote to push to               [string] [default: "origin"]
  --branch                        Git branch to push to             [string] [default: "gh-pages"]
  --source-branch                 Source branch to push from          [string] [default: "master"]
  --host-token-env-variable, -t   Github token for CI publish       [string] [default: "GH_TOKEN"]
  --aws-profile                   AWS profile to use for publishing. Use NONE to use no profile
                                  at all instead of "default".       [string] [default: "default"]
  --bucket-path                   AWS bucket path to use for publishing                   [string]
  --s3-sync-options               Additional options to pass to AWSCLI s3 sync            [string]

Getting Started

Install Storybook Deployer with:

npm i @storybook/storybook-deployer --save-dev

Then add a NPM script like this for github page:

{
  "scripts": {
    "deploy-storybook": "storybook-to-ghpages"
  }
}

or like this for AWS S3:

{
  "scripts": {
    "deploy-storybook": "storybook-to-aws-s3"
  }
}

Then you can run npm run deploy-storybook to deploy the Storybook.

Alternatively, you can execute Storybook Deployer directly using npx

npx -p @storybook/storybook-deployer storybook-to-ghpages
npx -p @storybook/storybook-deployer storybook-to-aws-s3

Custom Build Configuration

If you customize the build configuration with some additional params (like static file directory), then you need to expose another NPM script like this:

{
  "scripts": {
    "build-storybook": "build-storybook -s public"
  }
}

Configure Build Directory

If you need to configure the output directory you can supply the out flag.

npm run deploy-storybook -- --out=.out

Skip Build Step

If you have previously built your storybook output (through a different CI step, etc) and just need to publish it, specify the directory like this:

npm run deploy-storybook -- --existing-output-dir=.out

Skip Deploy Step

if you want to see how everything build without pushing to a remote, use the --dry-run flag.

npm run deploy-storybook -- --dry-run

Deploy a Monorepo

If you manage a monorepo with multiple storybooks you can pass the packages flag to deploy-storybook to scan a directory for package.jsons.

The following command will search the packages directory for packages. It will also generate a default index.html that links to all of the loaded storybooks.

npm run deploy-storybook -- --packages packages

Customize Monorepo `index.html`

To customize the monorepo index.html you can pass the monorepo-index-generator flag to deploy-storybook. This file should export a function that receive the following arguments and returns the html for the page.

an array of all the package.json data from the loaded storybooks as the first argument
the output directory

npm run deploy-storybook -- --monorepo-index-generator my-custom-generator.js

Deploying Storybook as part of a CI service

To deploy Storybook as part of a CI step, pass the ci flag to npm run deploy-storybook.

If the CI environment variable is set then this mode will be assumed, therefore no need to specify the ci flag.

Because pushing to GitHub as part of a CI step requires a personal access token, Storybook uses the GH_TOKEN environment variable, by default, to authenticate GitHub pushes.

This environment variable name can be configured via the host-token-env-variable flag.

For example, if your access token is stored in the GH_TOKEN environment variable

npm run deploy-storybook -- --ci

Or if your access token is stored in the GITHUB_TOKEN environment variable

npm run deploy-storybook -- --ci --host-token-env-variable=GITHUB_TOKEN

Deploying Storybook to GitHub Pages as part of a GitHub Action

If you are deploying Storybook to GitHub Pages from a repository belonging to an organization account on GitHub, you may need to specify a ${{ github.actor }} in addition to the ${{ secrets.GITHUB_TOKEN }} for your build step to be able to authenticate properly.

For instance:

- name: Deploy storybook to GitHub Pages
  run: npm run deploy-storybook -- --ci
  env:
    GH_TOKEN: ${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}

Custom deploy configuration

If you want to customize Git username, email or commit message, add this to package.json:

"storybook-deployer": {
  "gitUsername": "Custom Username",
  "gitEmail": "[email protected]",
  "commitMessage": "Deploy Storybook [skip ci]"
}

It will override the default configuration:

"storybook-deployer": {
  "gitUsername": "GH Pages Bot",
  "gitEmail": "[email protected]",
  "commitMessage": "Deploy Storybook to GitHub Pages"
}

To deploy Storybook to a remote other than origin, pass a --remote flag to npm run deploy-storybook. For example, to deploy to your upstream remote:

npm run deploy-storybook -- --remote=upstream

Or, to specify a target branch and serve your storybook with rawgit instead of gh-pages:

npm run deploy-storybook -- --branch=feature-branch

Or, to specify a source branch other than master, pass a --source-branch flag to npm run deploy-storybook:

npm run deploy-storybook -- --source-branch=release

Custom deploy configuration for S3

For AWS S3 deployment you must have awscli installed.

You must specify a bucket path with bucket-path option: my-bucket-name/path/to/destination-folder-in-bucket and have the rights to write to this bucket.

You can change the aws profile used to run the command with the aws-profile option.

storybook-to-aws-s3 --bucket-path=my-bucket-name/path/to/destination-folder-in-bucket --aws-profile=myprofile

You can exclude the aws profile by setting this flag to "NONE":

storybook-to-aws-s3 --bucket-path=my-bucket-name/path/to/destination-folder-in-bucket --aws-profile=NONE

You can provide arbitrary S3 sync options via the --s3-sync-options flag:

storybook-to-aws-s3 --bucket-path=bucket-name/bucket-path --s3-sync-options=--acl=public-read
storybook-to-aws-s3 --bucket-path=bucket-name/bucket-path --s3-sync-options="--acl=public-read --quiet"

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Andrew Lisowski} 💻 📖	_{Arunoda Susiripala} 💻 📖	_{Norbert de Langen} 💻 📖	_{Dan Dean} 💻 📖	_{Jason Unger} 💻 📖	_nkov 💻 📖	_{Tyler Sargent} 📖
_{Patrick Riley} 💻 📖	_jeanlucc 💻	_{Travis Bloom} 💻	_{Christophe Coevoet} 🚧	_{Michael Shilman} 🚧	_{Jae Bradley} 💻	_{Bryce Dorn} 🐛
_{Bao Pham} 💻	_{Ankur Patel} 💻	_{ZitaNemeckova} 💻	_{Lucas Machado} 💻	_{Jeri Sommers} 💻	_{Jimmy Andrade} 🚇 📖 💻	_{Nick Perez} 📖 💻
_Mitchell 📖	_erlendmiljo 📖