0
# Code Migration
1

2
Run Storybook codemods to migrate source files between versions and configurations. The migration system uses JSCodeshift to transform your source code, updating deprecated patterns, API changes, and configuration formats automatically.
3

4
## Capabilities
5

6
### Migrate Command
7

8
Execute codemods to transform source files for version migrations and configuration updates.
9

10
```bash { .api }
11
storybook migrate [migration] [options]
12

13
Parameters:
14
  migration                            Name of the migration to run
15

16
Options:
17
  -l, --list                           List available migrations
18
  -g, --glob <glob>                    Glob for files upon which to apply the migration (default: "**/*.js")
19
  -p, --parser <babel|babylon|flow|ts|tsx>  jscodeshift parser
20
  -c, --config-dir <dir-name>          Directory where to load Storybook configurations from
21
  -n, --dry-run                       Dry run: verify the migration exists and show the files to which it will be applied
22
  -r, --rename <from-to>               Rename suffix of matching files after codemod has been applied, e.g. ".js:.ts"
23
```
24

25
**Usage Examples:**
26

27
```bash
28
# List all available migrations
29
npx storybook migrate --list
30

31
# Run specific migration
32
npx storybook migrate csf-2-to-3
33

34
# Dry run to preview changes
35
npx storybook migrate csf-2-to-3 --dry-run
36

37
# Migrate with custom file glob
38
npx storybook migrate update-imports --glob "src/**/*.stories.js"
39

40
# Migrate TypeScript files
41
npx storybook migrate api-update --parser tsx --glob "**/*.stories.tsx"
42

43
# Migrate and rename file extensions
44
npx storybook migrate js-to-ts --rename ".js:.ts"
45

46
# Migrate with custom config directory
47
npx storybook migrate addon-update --config-dir .custom-storybook
48

49
# Migrate specific file patterns
50
npx storybook migrate story-format --glob "src/components/**/*.stories.*"
51
```
52

53
### Available Migrations
54

55
Common migrations provided by the Storybook ecosystem:
56

57
#### Story Format Migrations
58
- `csf-1-to-2` - Migrate Component Story Format v1 to v2
59
- `csf-2-to-3` - Migrate Component Story Format v2 to v3
60
- `storiesof-to-csf` - Convert storiesOf API to CSF
61
- `meta-3-to-2` - Downgrade CSF3 meta to CSF2 format
62

63
#### API Migrations
64
- `update-imports` - Update import statements for new packages
65
- `addon-info` - Migrate addon-info to addon-docs
66
- `addon-notes` - Migrate addon-notes to addon-docs
67
- `addon-knobs` - Migrate addon-knobs to addon-controls
68

69
#### Configuration Migrations
70
- `main-config-v6` - Migrate main.js to v6 format
71
- `webpack-config` - Update webpack configuration
72
- `typescript-config` - Migrate TypeScript configurations
73

74
#### Framework-Specific Migrations
75
- `react-docgen` - Update React docgen configuration
76
- `vue-docgen` - Update Vue docgen configuration
77
- `angular-ivy` - Migrate Angular Ivy configuration
78

79
### Parser Support
80

81
Choose the appropriate parser for your source files:
82

83
```bash
84
# JavaScript (default)
85
npx storybook migrate migration-name --parser babel
86

87
# TypeScript
88
npx storybook migrate migration-name --parser tsx
89

90
# Flow
91
npx storybook migrate migration-name --parser flow
92

93
# Babylon (alternative JavaScript parser)
94
npx storybook migrate migration-name --parser babylon
95
```
96

97
### File Targeting
98

99
Control which files are processed:
100

101
```bash
102
# Default: all JavaScript files
103
npx storybook migrate migration-name
104

105
# Custom glob pattern
106
npx storybook migrate migration-name --glob "src/**/*.stories.*"
107

108
# Multiple file types
109
npx storybook migrate migration-name --glob "**/*.{js,ts,jsx,tsx}"
110

111
# Specific directories
112
npx storybook migrate migration-name --glob "packages/*/src/**/*.stories.js"
113

114
# Exclude certain patterns
115
npx storybook migrate migration-name --glob "src/**/*.stories.js" --ignore "**/node_modules/**"
116
```
117

118
### File Renaming
119

120
Automatically rename files after migration:
121

122
```bash
123
# Rename .js to .ts
124
npx storybook migrate js-to-ts --rename ".js:.ts"
125

126
# Rename .jsx to .tsx  
127
npx storybook migrate jsx-to-tsx --rename ".jsx:.tsx"
128

129
# Complex renaming pattern
130
npx storybook migrate story-update --rename ".stories.js:.stories.ts"
131
```
132

133
### Dry Run Mode
134

135
Preview changes before applying them:
136

137
```bash
138
# See what files would be affected
139
npx storybook migrate csf-2-to-3 --dry-run
140

141
# Combine with custom glob for targeted preview
142
npx storybook migrate api-update --glob "src/**/*.stories.js" --dry-run
143
```
144

145
### Migration Development
146

147
Migrations are built using JSCodeshift transforms. Common patterns:
148

149
#### Import Statement Updates
150
```javascript
151
// Before migration
152
import { storiesOf } from '@storybook/react';
153

154
// After migration  
155
import type { Meta, StoryObj } from '@storybook/react';
156
```
157

158
#### API Pattern Updates
159
```javascript
160
// Before migration
161
storiesOf('Button', module)
162
  .add('Primary', () => <Button primary />);
163

164
// After migration
165
export default {
166
  title: 'Button',
167
  component: Button,
168
} as Meta<typeof Button>;
169

170
export const Primary: StoryObj<typeof Button> = {
171
  args: { primary: true },
172
};
173
```
174

175
#### Configuration Updates
176
```javascript
177
// Before migration
178
module.exports = {
179
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
180
  addons: ['@storybook/addon-essentials'],
181
};
182

183
// After migration
184
module.exports = {
185
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
186
  addons: [
187
    '@storybook/addon-links',
188
    '@storybook/addon-essentials',
189
  ],
190
  framework: '@storybook/react',
191
};
192
```
193

194
### Integration with @storybook/codemod
195

196
The migrate command delegates to the `@storybook/codemod` package:
197

198
```typescript { .api }
199
import { listCodemods, runCodemod } from '@storybook/codemod';
200

201
/**
202
 * List all available codemods
203
 */
204
function listCodemods(): string[];
205

206
/**
207
 * Run a specific codemod
208
 * @param codemodName - Name of the codemod to run
209
 * @param options - Codemod execution options
210
 */
211
function runCodemod(codemodName: string, options: CodemodOptions): Promise<void>;
212

213
interface CodemodOptions {
214
  glob: string;
215
  dryRun?: boolean;
216
  logger?: Logger;
217
  rename?: string;
218
  parser?: 'babel' | 'babylon' | 'flow' | 'ts' | 'tsx';
219
}
220
```
221

222
### Programmatic Usage
223

224
```typescript { .api }
225
import { migrate } from "@storybook/cli";
226

227
/**
228
 * Run migrations programmatically
229
 * @param migration - Name of the migration to run
230
 * @param options - Migration configuration
231
 */
232
function migrate(migration: string, options: CLIOptions): Promise<void>;
233

234
interface CLIOptions {
235
  glob: string;
236
  configDir?: string;
237
  dryRun?: boolean;
238
  list?: string[];
239
  rename?: string;
240
  parser?: 'babel' | 'babylon' | 'flow' | 'ts' | 'tsx';
241
}
242
```
243

244
**Programmatic Examples:**
245

246
```typescript
247
import { migrate } from "@storybook/cli";
248

249
// Run migration programmatically
250
await migrate("csf-2-to-3", {
251
  glob: "src/**/*.stories.js",
252
  dryRun: false,
253
  parser: "babel"
254
});
255

256
// List available migrations
257
await migrate(null, { list: true });
258
```
259

260
### Error Handling
261

262
Robust error handling for migration issues:
263

264
- **Syntax errors** - Graceful handling of unparseable files
265
- **Transform failures** - Detailed error reporting for failed transforms
266
- **File system errors** - Clear messaging for permission and access issues
267
- **Backup creation** - Automatic backups before applying destructive changes
268

269
### Best Practices
270

271
1. **Always run dry-run first** - Preview changes before applying
272
2. **Use version control** - Commit changes before running migrations
273
3. **Test after migration** - Verify your Storybook still works correctly
274
4. **Targeted migrations** - Use specific globs rather than blanket migrations
275
5. **Backup important files** - Create backups of critical configurations