0
# Automigration System
1
2
Detect and automatically fix compatibility issues, deprecated patterns, and configuration problems. The automigration system provides a comprehensive suite of automated fixes that keep Storybook configurations up-to-date and resolve common issues without manual intervention.
3
4
## Capabilities
5
6
### Automigrate Command
7
8
Automatically detect and apply fixes for known compatibility and configuration issues.
9
10
```bash { .api }
11
storybook automigrate [fixId] [options]
12
13
Parameters:
14
fixId Optional specific fix ID to run
15
16
Options:
17
-y, --yes Skip prompting the user
18
-n, --dry-run Only check for fixes, do not actually run them
19
--package-manager <npm|pnpm|yarn1|yarn2|bun> Force package manager
20
-l, --list List available migrations
21
-c, --config-dir <dir-name> Directory of Storybook configurations to migrate
22
-s, --skip-install Skip installing deps
23
--renderer <renderer-pkg-name> The renderer package for the framework Storybook is using
24
--skip-doctor Skip doctor check
25
```
26
27
**Usage Examples:**
28
29
```bash
30
# Run all applicable automigrations
31
npx storybook automigrate
32
33
# List available automigrations
34
npx storybook automigrate --list
35
36
# Run specific automigration by ID
37
npx storybook automigrate addon-docs-config
38
39
# Dry run to see what would be fixed
40
npx storybook automigrate --dry-run
41
42
# Run without prompts
43
npx storybook automigrate --yes
44
45
# Skip dependency installation
46
npx storybook automigrate --skip-install
47
48
# Specify custom config directory
49
npx storybook automigrate --config-dir .custom-storybook
50
51
# Force specific package manager
52
npx storybook automigrate --package-manager yarn1
53
```
54
55
### Fix Categories
56
57
Automigrations are organized into several categories:
58
59
#### Configuration Fixes
60
- **main.js/ts updates** - Modernize configuration format
61
- **Framework configuration** - Update framework-specific settings
62
- **Builder configuration** - Migrate builder options
63
- **Addon configuration** - Fix addon configurations
64
65
#### Dependency Fixes
66
- **Package updates** - Update outdated dependencies
67
- **Peer dependency resolution** - Fix peer dependency issues
68
- **Duplicate dependency removal** - Clean up duplicate packages
69
- **Version compatibility** - Resolve version conflicts
70
71
#### Code Fixes
72
- **Import statement updates** - Modernize import patterns
73
- **API migrations** - Update deprecated API usage
74
- **TypeScript fixes** - Fix TypeScript configuration issues
75
- **ESLint rule updates** - Update ESLint configurations
76
77
#### Framework-Specific Fixes
78
- **React fixes** - React-specific automigrations
79
- **Vue fixes** - Vue-specific automigrations
80
- **Angular fixes** - Angular-specific automigrations
81
- **Web Components fixes** - Web Components automigrations
82
83
### Fix Status Types
84
85
Each fix can have one of several statuses:
86
87
```typescript { .api }
88
enum FixStatus {
89
SKIPPED = "skipped", // Fix was not applicable
90
APPLIED = "applied", // Fix was successfully applied
91
FAILED = "failed", // Fix failed to apply
92
UNNECESSARY = "unnecessary", // Fix was not needed
93
CHECK_FAILED = "check_failed" // Pre-check failed
94
}
95
```
96
97
### Multi-Project Support
98
99
Handle monorepos and multiple Storybook configurations:
100
101
```bash
102
# Automatically discover and migrate all Storybook projects
103
npx storybook automigrate
104
105
# Specify multiple config directories
106
npx storybook automigrate --config-dir packages/app/.storybook --config-dir packages/lib/.storybook
107
```
108
109
### Available Automigrations
110
111
Common automigrations include:
112
113
#### Addon Migrations
114
- `addon-docs-config` - Update addon-docs configuration
115
- `addon-controls-config` - Migrate addon-controls settings
116
- `addon-actions-config` - Update addon-actions configuration
117
- `remove-addon-interactions` - Remove deprecated addon-interactions
118
119
#### Framework Migrations
120
- `react-vite-config` - Update React + Vite configuration
121
- `nextjs-config` - Migrate Next.js Storybook setup
122
- `angular-config` - Update Angular Storybook configuration
123
124
#### Core Migrations
125
- `webpack5-config` - Migrate to Webpack 5
126
- `main-config-format` - Update main.js format
127
- `preview-config-format` - Update preview.js format
128
- `typescript-config` - Fix TypeScript configuration
129
130
### Interactive vs Automated Mode
131
132
#### Interactive Mode (default)
133
- Prompts for confirmation before applying fixes
134
- Shows detailed information about each fix
135
- Allows selective application of fixes
136
137
#### Automated Mode (`--yes`)
138
- Applies all applicable fixes without prompts
139
- Ideal for CI/CD pipelines
140
- Provides summary of applied fixes
141
142
### Dry Run Mode
143
144
Preview what fixes would be applied without making changes:
145
146
```bash
147
# See what would be fixed
148
npx storybook automigrate --dry-run
149
150
# Dry run for specific fix
151
npx storybook automigrate addon-docs-config --dry-run
152
```
153
154
### Integration with Other Commands
155
156
Automigrations are automatically triggered by:
157
158
- **upgrade command** - Runs relevant migrations after version upgrades
159
- **add command** - Applies addon-specific fixes when adding addons
160
- **doctor command** - Suggests automigrations for detected issues
161
162
### Programmatic Usage
163
164
```typescript { .api }
165
import { doAutomigrate, runAutomigrations } from "@storybook/cli";
166
167
/**
168
* Main automigration entry point
169
* @param options - Automigration configuration
170
*/
171
function doAutomigrate(options: AutofixOptions): Promise<void>;
172
173
/**
174
* Run automigrations across multiple projects
175
* @param projects - List of project configurations
176
* @param options - Automigration options
177
*/
178
function runAutomigrations(
179
projects: CollectProjectsSuccessResult[],
180
options: AutofixOptions
181
): Promise<AutomigrationResult[]>;
182
183
interface AutofixOptions {
184
fixId?: string;
185
yes?: boolean;
186
dryRun?: boolean;
187
packageManager?: PackageManagerName;
188
list?: boolean;
189
configDir?: string;
190
skipInstall?: boolean;
191
renderer?: string;
192
skipDoctor?: boolean;
193
}
194
195
interface AutomigrationResult {
196
fixId: string;
197
status: FixStatus;
198
description?: string;
199
details?: string;
200
}
201
202
interface Fix {
203
id: string;
204
name: string;
205
description: string;
206
check: (options: CheckOptions) => Promise<CheckResult>;
207
run: (options: RunOptions) => Promise<RunResult>;
208
}
209
```
210
211
**Programmatic Examples:**
212
213
```typescript
214
import { doAutomigrate } from "@storybook/cli";
215
216
// Run all automigrations programmatically
217
await doAutomigrate({
218
yes: true,
219
dryRun: false,
220
packageManager: "npm"
221
});
222
223
// Run specific fix programmatically
224
await doAutomigrate({
225
fixId: "addon-docs-config",
226
yes: true
227
});
228
```
229
230
### Custom Fix Development
231
232
Create custom automigrations for your specific needs:
233
234
```typescript { .api }
235
interface CustomFix extends Fix {
236
id: string;
237
name: string;
238
description: string;
239
240
// Check if fix is applicable
241
check(options: CheckOptions): Promise<CheckResult>;
242
243
// Apply the fix
244
run(options: RunOptions): Promise<RunResult>;
245
}
246
```
247
248
### Error Handling and Rollback
249
250
Robust error handling with rollback capabilities:
251
252
- **Pre-check validation** - Validates environment before applying fixes
253
- **Atomic operations** - Either fully applies or fully rolls back fixes
254
- **Backup creation** - Creates backups before applying destructive changes
255
- **Rollback mechanism** - Can undo changes if issues are detected