0
# Version Management
1
2
Upgrade Storybook packages to newer versions with compatibility checks and automigrations. The upgrade system handles dependency management, version conflicts, and automatically applies necessary migrations to keep your Storybook installation up-to-date and compatible.
3
4
## Capabilities
5
6
### Upgrade Command
7
8
Upgrades Storybook packages to the latest compatible version with automated migration support.
9
10
```bash { .api }
11
storybook upgrade [options]
12
13
Options:
14
--package-manager <npm|pnpm|yarn1|yarn2|bun> Force package manager for installing dependencies
15
-y, --yes Skip prompting the user
16
-f, --force Force the upgrade, skipping autoblockers
17
-n, --dry-run Only check for upgrades, do not install
18
-s, --skip-check Skip postinstall version and automigration checks
19
-c, --config-dir <dir-name...> Directory(ies) where to load Storybook configurations from
20
```
21
22
**Usage Examples:**
23
24
```bash
25
# Basic upgrade to latest version
26
npx storybook upgrade
27
28
# Upgrade with specific package manager
29
npx storybook upgrade --package-manager yarn1
30
31
# Check what would be upgraded without installing
32
npx storybook upgrade --dry-run
33
34
# Force upgrade, bypassing compatibility checks
35
npx storybook upgrade --force
36
37
# Skip prompts and use defaults
38
npx storybook upgrade --yes
39
40
# Upgrade and skip postinstall checks
41
npx storybook upgrade --skip-check
42
43
# Upgrade multiple Storybook configurations
44
npx storybook upgrade --config-dir .storybook --config-dir packages/*/\.storybook
45
```
46
47
### Version Detection
48
49
The upgrade system detects and manages various Storybook package versions:
50
51
1. **Core packages** - `@storybook/core-*`, `storybook`
52
2. **Framework packages** - `@storybook/react`, `@storybook/vue3`, etc.
53
3. **Addon packages** - `@storybook/addon-*`
54
4. **Builder packages** - `@storybook/builder-*`
55
5. **CLI packages** - `@storybook/cli`
56
57
### Autoblock System
58
59
Automated checks prevent problematic upgrades:
60
61
- **Incompatible dependencies** - Blocks upgrades that would break existing functionality
62
- **Framework conflicts** - Prevents version mismatches between framework packages
63
- **Node.js version** - Ensures Node.js compatibility
64
- **Package manager issues** - Detects and prevents known package manager problems
65
66
### Multi-Project Support
67
68
Handle monorepos and multiple Storybook instances:
69
70
```bash
71
# Upgrade all Storybook configurations in a monorepo
72
npx storybook upgrade --config-dir packages/app/.storybook --config-dir packages/components/.storybook
73
74
# Automatically discover Storybook configurations
75
npx storybook upgrade # Discovers .storybook directories automatically
76
```
77
78
### Dependency Management
79
80
The upgrade process handles:
81
82
1. **Version consistency** - Ensures all Storybook packages use compatible versions
83
2. **Peer dependencies** - Updates peer dependencies as needed
84
3. **Dev vs production** - Correctly categorizes dependencies
85
4. **Lock file updates** - Updates package-lock.json, yarn.lock, or pnpm-lock.yaml
86
87
### Upgrade Validation
88
89
Post-upgrade validation includes:
90
91
- **Version consistency checks** - Verifies all packages are compatible
92
- **Configuration validation** - Ensures configs are valid after upgrade
93
- **Automatic migrations** - Runs necessary codemods and fixes
94
- **Doctor checks** - Identifies potential issues
95
96
### Programmatic Usage
97
98
```typescript { .api }
99
import { upgrade } from "@storybook/cli";
100
101
/**
102
* Upgrade Storybook packages programmatically
103
* @param options - Upgrade configuration
104
*/
105
function upgrade(options: UpgradeOptions): Promise<void>;
106
107
interface UpgradeOptions {
108
packageManager?: PackageManagerName;
109
yes?: boolean;
110
force?: boolean;
111
dryRun?: boolean;
112
skipCheck?: boolean;
113
configDir?: string[];
114
}
115
116
/**
117
* Extract Storybook version from npm output line
118
* @param line - npm output line
119
* @returns Package info or null
120
*/
121
function getStorybookVersion(line: string): Package | null;
122
123
/**
124
* Check version consistency across Storybook packages
125
* @param packages - List of package information
126
* @returns Consistency check results
127
*/
128
function checkVersionConsistency(packages: Package[]): ConsistencyResult;
129
130
interface Package {
131
package: string;
132
version: string;
133
}
134
135
type PackageManagerName = "npm" | "pnpm" | "yarn1" | "yarn2" | "bun";
136
```
137
138
**Programmatic Examples:**
139
140
```typescript
141
import { upgrade, getStorybookVersion } from "@storybook/cli";
142
143
// Upgrade programmatically
144
await upgrade({
145
packageManager: "npm",
146
yes: true,
147
dryRun: false
148
});
149
150
// Parse version from npm output
151
const packageInfo = getStorybookVersion("@storybook/react@7.6.17");
152
// Returns: { package: "@storybook/react", version: "7.6.17" }
153
```
154
155
### Version Compatibility
156
157
The upgrade system maintains compatibility with:
158
159
- **LTS versions** - Long-term support versions with extended compatibility
160
- **Current versions** - Latest stable releases
161
- **Prerelease versions** - Alpha, beta, and release candidate versions
162
- **Framework versions** - Ensures framework adapter compatibility
163
164
### Upgrade Strategies
165
166
Different approaches for different scenarios:
167
168
1. **Patch upgrades** - Safe bug fixes and minor improvements
169
2. **Minor upgrades** - New features with backward compatibility
170
3. **Major upgrades** - Breaking changes requiring migration
171
4. **Prerelease upgrades** - Early access to upcoming features
172
173
### Error Handling
174
175
Robust error handling for common upgrade issues:
176
177
- **Network failures** - Retry logic for package downloads
178
- **Permission errors** - Clear guidance for permission issues
179
- **Dependency conflicts** - Resolution strategies for conflicts
180
- **Migration failures** - Rollback options for failed upgrades