or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-storybook--storybook-deployer

Deploy Storybook applications to static hosting services including GitHub Pages and AWS S3

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@storybook/storybook-deployer@2.8.x

To install, run

npx @tessl/cli install tessl/npm-storybook--storybook-deployer@2.8.0

index.mddocs/

Storybook Deployer

Storybook Deployer is a command-line tool that allows you to deploy your Storybook applications to static hosting services. It provides automated deployment workflows for GitHub Pages and AWS S3, with comprehensive configuration options for CI/CD integration, monorepo support, and custom deployment settings.

Package Information

  • Package Name: @storybook/storybook-deployer
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install @storybook/storybook-deployer --save-dev

Core Commands

The package provides two main executable commands:

# Deploy to GitHub Pages
storybook-to-ghpages [options]

# Deploy to AWS S3
storybook-to-aws-s3 [options]

Basic Usage

GitHub Pages Deployment

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

AWS S3 Deployment

{
  "scripts": {
    "deploy-storybook": "storybook-to-aws-s3 --bucket-path my-bucket/storybook"
  }
}
npm run deploy-storybook

Direct Execution

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

# Or if installed globally
storybook-to-ghpages --help
storybook-to-aws-s3 --help

Capabilities

GitHub Pages Deployment

Deploys Storybook to GitHub Pages by building the Storybook, creating a temporary git repository, and pushing to the gh-pages branch.

storybook-to-ghpages [options]

# Core Options:
--help, -h                      # Show help information (boolean)
--existing-output-dir, -e       # Use pre-built storybook output directory (string)
--out, -o                       # Configure custom output directory (string)
--packages, -p                  # Directory for package.jsons - enables monorepo support (string)
--monorepo-index-generator, -m  # Path to custom monorepo index.html generator function (string)
--script, -s                    # Specify build script name in package.json (string, default: 'build-storybook')
--ci                            # Deploy in CI mode - enables token-based authentication (boolean)
--dry-run                       # Build without publishing (boolean)

# GitHub Pages Specific Options:
--remote                        # Git remote to push to (string, default: 'origin')
--branch                        # Target git branch for deployment (string, default: 'gh-pages')
--source-branch                 # Source branch to push from (string, default: 'master')
--host-token-env-variable, -t   # Environment variable name for GitHub token (string, default: 'GH_TOKEN')

Usage Examples:

# Basic deployment
storybook-to-ghpages

# Custom output directory
storybook-to-ghpages --out=.storybook-static

# Skip build step (use existing build)
storybook-to-ghpages --existing-output-dir=.storybook-static

# CI deployment with custom token
storybook-to-ghpages --ci --host-token-env-variable=GITHUB_TOKEN

# Deploy to custom branch
storybook-to-ghpages --branch=docs --source-branch=main

# Monorepo deployment
storybook-to-ghpages --packages=packages

# Dry run for testing
storybook-to-ghpages --dry-run

AWS S3 Deployment

Deploys Storybook to AWS S3 by building the Storybook and syncing files to the specified bucket using AWS CLI.

storybook-to-aws-s3 [options]

# Core Options (same as GitHub Pages):
--help, -h                      # Show help information (boolean)
--existing-output-dir, -e       # Use pre-built storybook output directory (string)
--out, -o                       # Configure custom output directory (string)
--packages, -p                  # Directory for package.jsons - enables monorepo support (string)
--monorepo-index-generator, -m  # Path to custom monorepo index.html generator function (string)
--script, -s                    # Specify build script name in package.json (string, default: 'build-storybook')
--ci                            # Deploy in CI mode (boolean)
--dry-run                       # Build without publishing (boolean)

# AWS S3 Specific Options:
--aws-profile                   # AWS profile for deployment (string, default: 'default', use 'NONE' for no profile)
--bucket-path                   # S3 bucket path for deployment (string, required)
--s3-sync-options               # Additional AWS CLI s3 sync options (string)

Usage Examples:

# Basic S3 deployment (requires bucket-path)
storybook-to-aws-s3 --bucket-path=my-bucket-name/storybook

# With custom AWS profile
storybook-to-aws-s3 --bucket-path=my-bucket/app --aws-profile=production

# No AWS profile (useful for EC2 instance roles)
storybook-to-aws-s3 --bucket-path=my-bucket/app --aws-profile=NONE

# Additional S3 sync options
storybook-to-aws-s3 --bucket-path=my-bucket/app --s3-sync-options="--delete --cache-control max-age=31536000"

# With custom build output
storybook-to-aws-s3 --bucket-path=my-bucket/app --existing-output-dir=dist-storybook

Monorepo Support

Both commands support monorepo deployment by automatically detecting packages with Storybook configurations.

# Monorepo Options:
--packages, -p                  # Directory containing packages (string)
--monorepo-index-generator, -m  # Path to custom index generator (string)

Monorepo Usage:

# Deploy all packages in a monorepo
storybook-to-ghpages --packages=packages

# Custom monorepo index generator
storybook-to-ghpages --packages=packages --monorepo-index-generator=./custom-index.js

The tool automatically:

  • Discovers packages with .storybook directories or build scripts
  • Builds each package's Storybook
  • Creates a unified index page linking to all package Storybooks
  • Supports custom index generation via JavaScript function

Custom Build Configuration

Configure custom build scripts and output directories.

# Build Configuration Options:
--script, -s                    # Build script name (string, default: 'build-storybook')
--out, -o                       # Output directory (string)
--existing-output-dir, -e       # Skip build, use existing directory (string)

Build Examples:

# Custom build script
storybook-to-ghpages --script=build-docs

# Custom output directory
storybook-to-ghpages --out=storybook-dist

# Use existing build (skip build step)
storybook-to-ghpages --existing-output-dir=./dist

CI/CD Integration

Both commands support continuous integration environments with token-based authentication.

# CI Options:
--ci                            # Enable CI mode (boolean)
--host-token-env-variable, -t   # GitHub token environment variable (string, default: 'GH_TOKEN')
--dry-run                       # Test without deploying (boolean)

CI Examples:

# GitHub Actions / CI deployment
storybook-to-ghpages --ci

# Custom token variable
storybook-to-ghpages --ci --host-token-env-variable=DEPLOY_TOKEN

# Test deployment process
storybook-to-ghpages --ci --dry-run

Configuration

Package.json Configuration

Optional configuration can be added to your package.json:

{
  "storybook-deployer": {
    "gitUsername": "Custom Bot Name",
    "gitEmail": "bot@example.com", 
    "commitMessage": "Deploy Storybook to GitHub Pages"
  }
}

Configuration Properties:

  • gitUsername: Git username for deployment commits (string, default: 'GH Pages Bot')
  • gitEmail: Git email for deployment commits (string, default: 'hello@ghbot.com')
  • commitMessage: Commit message for deployment (string, default: 'Deploy Storybook to GitHub Pages')

Environment Variables

GitHub Pages:

  • GH_TOKEN (or custom): GitHub personal access token for CI deployment
  • CI: Automatically detected CI environment

AWS S3:

  • Standard AWS CLI environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, etc.)
  • AWS profile configuration via ~/.aws/credentials

Error Handling

The tool validates required inputs and provides clear error messages:

  • Missing git remote: "This project is not configured with a remote git repo"
  • Missing S3 bucket: "This command needs a bucket path"
  • Build failures: Command execution errors with exit codes
  • Git operation failures: Detailed error output for git commands
  • AWS CLI failures: S3 sync error reporting

External Dependencies

Required:

  • Node.js and npm/yarn
  • Git command-line tool
  • AWS CLI (for S3 deployment only)

Internal Dependencies:

  • yargs: Command-line argument parsing
  • shelljs: Cross-platform shell commands
  • git-url-parse: Git URL parsing
  • parse-repo: Repository URL parsing
  • glob: File pattern matching