0
# Storybook Deployer
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @storybook/storybook-deployer
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @storybook/storybook-deployer --save-dev`
10

11
## Core Commands
12

13
The package provides two main executable commands:
14

15
```bash
16
# Deploy to GitHub Pages
17
storybook-to-ghpages [options]
18

19
# Deploy to AWS S3
20
storybook-to-aws-s3 [options]
21
```
22

23
## Basic Usage
24

25
### GitHub Pages Deployment
26

27
```json
28
{
29
  "scripts": {
30
    "deploy-storybook": "storybook-to-ghpages"
31
  }
32
}
33
```
34

35
```bash
36
npm run deploy-storybook
37
```
38

39
### AWS S3 Deployment
40

41
```json
42
{
43
  "scripts": {
44
    "deploy-storybook": "storybook-to-aws-s3 --bucket-path my-bucket/storybook"
45
  }
46
}
47
```
48

49
```bash
50
npm run deploy-storybook
51
```
52

53
### Direct Execution
54

55
```bash
56
# Using npx
57
npx -p @storybook/storybook-deployer storybook-to-ghpages
58
npx -p @storybook/storybook-deployer storybook-to-aws-s3
59

60
# Or if installed globally
61
storybook-to-ghpages --help
62
storybook-to-aws-s3 --help
63
```
64

65
## Capabilities
66

67
### GitHub Pages Deployment
68

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

71
```bash { .api }
72
storybook-to-ghpages [options]
73

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

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

91
**Usage Examples:**
92

93
```bash
94
# Basic deployment
95
storybook-to-ghpages
96

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

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

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

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

109
# Monorepo deployment
110
storybook-to-ghpages --packages=packages
111

112
# Dry run for testing
113
storybook-to-ghpages --dry-run
114
```
115

116
### AWS S3 Deployment
117

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

120
```bash { .api }
121
storybook-to-aws-s3 [options]
122

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

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

139
**Usage Examples:**
140

141
```bash
142
# Basic S3 deployment (requires bucket-path)
143
storybook-to-aws-s3 --bucket-path=my-bucket-name/storybook
144

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

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

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

154
# With custom build output
155
storybook-to-aws-s3 --bucket-path=my-bucket/app --existing-output-dir=dist-storybook
156
```
157

158
### Monorepo Support
159

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

162
```bash { .api }
163
# Monorepo Options:
164
--packages, -p                  # Directory containing packages (string)
165
--monorepo-index-generator, -m  # Path to custom index generator (string)
166
```
167

168
**Monorepo Usage:**
169

170
```bash
171
# Deploy all packages in a monorepo
172
storybook-to-ghpages --packages=packages
173

174
# Custom monorepo index generator
175
storybook-to-ghpages --packages=packages --monorepo-index-generator=./custom-index.js
176
```
177

178
The tool automatically:
179
- Discovers packages with `.storybook` directories or build scripts
180
- Builds each package's Storybook
181
- Creates a unified index page linking to all package Storybooks
182
- Supports custom index generation via JavaScript function
183

184
### Custom Build Configuration
185

186
Configure custom build scripts and output directories.
187

188
```bash { .api }
189
# Build Configuration Options:
190
--script, -s                    # Build script name (string, default: 'build-storybook')
191
--out, -o                       # Output directory (string)
192
--existing-output-dir, -e       # Skip build, use existing directory (string)
193
```
194

195
**Build Examples:**
196

197
```bash
198
# Custom build script
199
storybook-to-ghpages --script=build-docs
200

201
# Custom output directory
202
storybook-to-ghpages --out=storybook-dist
203

204
# Use existing build (skip build step)
205
storybook-to-ghpages --existing-output-dir=./dist
206
```
207

208
### CI/CD Integration
209

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

212
```bash { .api }
213
# CI Options:
214
--ci                            # Enable CI mode (boolean)
215
--host-token-env-variable, -t   # GitHub token environment variable (string, default: 'GH_TOKEN')
216
--dry-run                       # Test without deploying (boolean)
217
```
218

219
**CI Examples:**
220

221
```bash
222
# GitHub Actions / CI deployment
223
storybook-to-ghpages --ci
224

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

228
# Test deployment process
229
storybook-to-ghpages --ci --dry-run
230
```
231

232
## Configuration
233

234
### Package.json Configuration
235

236
Optional configuration can be added to your `package.json`:
237

238
```json { .api }
239
{
240
  "storybook-deployer": {
241
    "gitUsername": "Custom Bot Name",
242
    "gitEmail": "bot@example.com", 
243
    "commitMessage": "Deploy Storybook to GitHub Pages"
244
  }
245
}
246
```
247

248
**Configuration Properties:**
249

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

254
### Environment Variables
255

256
**GitHub Pages:**
257
- `GH_TOKEN` (or custom): GitHub personal access token for CI deployment
258
- `CI`: Automatically detected CI environment
259

260
**AWS S3:**
261
- Standard AWS CLI environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, etc.)
262
- AWS profile configuration via `~/.aws/credentials`
263

264
## Error Handling
265

266
The tool validates required inputs and provides clear error messages:
267

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

274
## External Dependencies
275

276
**Required:**
277
- Node.js and npm/yarn
278
- Git command-line tool
279
- AWS CLI (for S3 deployment only)
280

281
**Internal Dependencies:**
282
- `yargs`: Command-line argument parsing
283
- `shelljs`: Cross-platform shell commands  
284
- `git-url-parse`: Git URL parsing
285
- `parse-repo`: Repository URL parsing
286
- `glob`: File pattern matching