Svelte Storybook Migrate Action

Migrate Storybook configurations, story files, and addons to newer versions including Svelte CSF v5 and the @storybook/sveltekit framework package.

When to Use This Command

Run this command when...

• You need to upgrade from Storybook 6.x to 7.x or 7.x to 8.x and want automated migration of configuration files, story syntax, and addon compatibility
• Your stories use the legacy Svelte CSF v4 format and need conversion to the modern v5 defineMeta and defineStory pattern
• You want to migrate from @storybook/svelte-vite to @storybook/sveltekit for proper SvelteKit module mocking and routing support

Do NOT use this command when...

• You are setting up Storybook for the first time -- use the setup command instead
• Your Storybook is already on the latest version and uses current story syntax

Quick Start

Copy
# .claude/commands/svelte-storybook-migrate-action.md
# Migrate Storybook version
Migrate: $ARGUMENTS

Copy
# Run the command
claude "svelte-storybook-migrate-action upgrade from Storybook 7 to 8 with CSF v5 story conversion"

Expected output:
- Package.json dependency updates
- Main.js/main.ts configuration migration
- Story file syntax conversion (CSF v4 to v5)
- Addon compatibility check and updates
- Breaking change inventory with resolutions

Core Concepts

Concept	Description
CSF Versions	Component Story Format evolution from v1/v2/v3 (object exports) to v5 (defineMeta)
Framework Package	Migration from @storybook/svelte-vite to @storybook/sveltekit
Addon Compatibility	Ensuring addons work with the target Storybook version
Configuration Migration	Updating main.js exports, preview.js decorators, and manager.js
Story Codemods	Automated syntax transformation of story files to new patterns

Migration Workflow:

  Current Storybook (v6/v7)
       |
  [Analyze Current Config]
       |
  [Identify Breaking Changes]
       |
  +----+----+----+
  |    |    |    |
 Config Stories Addons Deps
  |    |    |    |
  [Apply Migrations]
       |
  [Verify Build]
       |
  Updated Storybook (v7/v8)

Configuration

Parameter	Default	Description
Source Version	Auto-detect	Current Storybook major version
Target Version	Latest stable	Storybook version to migrate to
CSF Target	v5	Target Component Story Format version
Framework	@storybook/sveltekit	Target framework package
Dry Run	No	Preview changes without writing files

Best Practices

1. Commit before migrating -- create a clean git commit before running the migration so you can easily review changes and revert if something breaks
2. Migrate incrementally -- if jumping multiple major versions, migrate one version at a time (6 to 7, then 7 to 8) rather than skipping versions
3. Update addons separately -- after the core migration succeeds, update addons one at a time to isolate compatibility issues
4. Test every story -- run through all stories in the browser after migration. Automated migration handles syntax but may miss rendering regressions
5. Review CSF v5 patterns -- familiarize yourself with defineMeta and defineStory syntax before migrating so you can spot and fix any conversion issues

Common Issues

1. Stories fail to render after migration -- CSF v5 has a different decorator application order. Check that your decorators are compatible with the new format
2. SvelteKit modules not mocked -- after migrating to @storybook/sveltekit, you need to configure module mocks in preview.js for $app/* imports
3. Addon version conflicts -- some addons lag behind major Storybook releases. Check each addon's compatibility matrix and temporarily disable incompatible ones