@storybook/storybook-deployer

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": "[e-mail]",
  "commitMessage": "Deploy Storybook [skip ci]"
}

It will override the default configuration:

"storybook-deployer": {
  "gitUsername": "GH Pages Bot",
  "gitEmail": "[e-mail]",
  "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 📖	George Marshall 💻

This project follows the all-contributors specification. Contributions of any kind welcome!