sv migrate - Svelte Migration Tool: AI-Optimized Technical Reference

Overview

Official Svelte CLI tool that automates migration between major Svelte versions. Handles ~80% of mechanical upgrades automatically but requires manual intervention for complex patterns.

Critical Capabilities & Limitations

What sv migrate Successfully Handles

• Basic state conversion: let count = 0 → let count = $state(0)
• Reactive statements: $: doubled = count * 2 → let doubled = $derived(count * 2)
• Props patterns: export let name → destructured $props()
• Event handlers: on:click → onclick
• SvelteKit routing updates: API pattern migrations for SvelteKit 2
• Legacy cleanup: Svelte 3/4 deprecated patterns

Critical Failure Points

• Complex reactive patterns: Multiple dependent $: statements
• Custom stores: Intricate reactivity patterns with lifecycle dependencies
• Third-party library integration: Component libraries depending on Svelte 4 internals
• Edge cases: Custom event dispatchers, slot manipulation, dynamic component patterns
• Undocumented Svelte internals: Direct DOM manipulation, programmatic component creation

Resource Requirements & Timelines

Project Size vs Migration Time

Project Size	Tool Runtime	Total Debug Time	Complexity Factor
Small (10-20 components)	30 seconds	1 hour	Simple patterns only
Medium (50 components)	2-3 minutes	Half-day	10-15 @migration comments
Large (100+ components)	5-10 minutes	2-3 days	Custom stores, complex patterns

Prerequisites (Critical)

• Node.js 16+ (version tolerance high)
• Clean git state - Tool can corrupt files on weird syntax
• Passing tests - Baseline functionality verification
• Component library compatibility check - Most break initially

Implementation Workflow

Pre-Migration Safety Protocol

git add . && git commit -m "Before migration - backup point"
git checkout -b svelte-5-migration
git status  # Must be clean

Core Commands

# Interactive picker
npx sv migrate

# Direct Svelte 5 migration
npx sv migrate svelte-5

# Find manual work locations
grep -r "@migration" src/

Post-Migration Debugging Process

1. Dependency resolution: npm install (often breaks)
2. Manual fixes: Address @migration comments
3. Test suite: npm test (component behavior changes)
4. Manual testing: Forms, state flows, component communication

Critical Warnings & Failure Modes

Dependency Hell Indicators

• npm ERR! peer dep missing - Library requires Svelte 4
• Build failures from TypeScript config incompatibility
• Test failures from testing library rune incompatibility

Common Breaking Patterns

• Custom stores with lifecycle dependencies
• Dynamic component patterns: <svelte:component this={component}>
• Multiple interdependent reactive statements
• Build tool incompatibility: Custom preprocessors, webpack configs

Rollback Strategies

# Nuclear option - complete revert
git checkout . && git clean -fd

# Selective revert
git checkout HEAD -- src/components/broken-component.svelte

Testing & Validation Requirements

Immediate Testing Protocol

• Test suite execution: Component behavior changes likely
• Manual testing checklist: Forms (two-way binding), state flows, component communication
• Browser console: Deprecation warnings expected
• Performance verification: Not automatically better despite claims

Common Test Failures

• Tests depending on specific DOM structure (runes change rendering)
• Component internal/lifecycle behavior tests
• Component store or complex reactive pattern tests

Compatibility & Library Support

Library Categories by Risk Level

• High Risk: Older UI component libraries, custom animation libraries
• Medium Risk: Libraries with deep Svelte integration
• Low Risk: Basic stores (writable, readable, derived)

TypeScript Integration

• Usually compatible with stricter type checking
• May reveal previously hidden type errors
• Component types change from class-based to function-based

Decision Support Information

When to Use sv migrate

• Projects with standard Svelte patterns
• When manual migration time exceeds debugging time
• As starting point for complex projects (not complete solution)

Alternative Approaches

• VS Code "Migrate Component" command: Safer for complex components
• Svelte Playground migrate button: Testing individual patterns
• Manual migration: Complex patterns requiring full control

Operational Intelligence

Hidden Costs

• Library replacement time: Popular libraries may lack Svelte 5 support
• Team learning curve: New rune patterns require training
• Performance regression debugging: Optimization patterns may change behavior

Success Indicators

• Clean migration with <5 @migration comments
• All tests pass after basic fixes
• No library compatibility issues
• Performance maintains or improves

Failure Recovery

• Phased approach: Migrate components incrementally
• Branch-based migration: Test before merging
• Component-by-component validation: Isolate problems

Resource Links (Operational)

• Migration Issues: github.com/sveltejs/svelte/discussions/13705
• Real experiences: dev.to migration articles with timelines
• VS Code extension: "Migrate Component" for individual files
• Svelte Discord: #svelte-5 channel for specific problems
• Playground testing: svelte.dev/playground migrate feature

Key Takeaway

sv migrate handles mechanical conversion well but complex applications require significant manual work. Treat as starting point (80% automation) with planned debugging phase (20% manual). Success depends on project complexity, not just size.