Overview

Version 5.0 is a major release built for Svelte 5, featuring a complete rewrite using runes instead of stores. This guide covers all breaking changes and provides step-by-step upgrade instructions.

Important: v5.0 requires Svelte 5.0 or later. If you're still on Svelte 4, continue using svelte-spa-router v4.x.

Breaking Changes Summary

Changev4.x (Old)v5.0 (New)
State managementSvelte storesSvelte 5 runes ($state, $derived)
State access$location, $paramslocation(), routeParams()
Parameter nameparamsrouteParams
Router eventsonrouteLoadingonRouteLoading (camelCase)
Logger APIsetDebugLoggingEnabled()enableLogging(), setCategoryLevel()
Unauthorized handlingHash-based navigation + onUnauthorizedComponent-based + configurePermissions()
Import paths/stores export path existsNo /stores path - removed

Step-by-Step Migration

1. Update Dependencies

 
 
 
 
 
2. Update State Access Patterns
 
Replace store subscriptions with function calls:
 
Old v4.x code 
 
 
 
New v5.0 code 
 
 
 
3. Update Route Component Props
 
Route components receive params via $props():
 
Old v4.x code 
 
 
 
New v5.0 code 
 
 
 
4. Update Router Event Handlers
 
Event handler props are now camelCase:
 
Old v4.x code 
 
 
 
New v5.0 code 
 
 
 
5. Update Logger API
 
The debug logging API has been completely redesigned:
 
Old v4.x code 
 
 
 
New v5.0 code 
 
 
 
6. Update Permission System
 
Unauthorized handling is now component-based:
 
Old v4.x code 
 
 
 
New v5.0 code 
 
 
 
7. Remove /stores Import Path
 
The /stores export path no longer exists:
 
 
 
 
Common Migration Issues
 
Issue: "Cannot read properties of undefined (reading 'before')"
 
Cause: Using sync component import with createProtectedRoute()
 
Solution: This is fixed in v5.0.0. Both patterns now work:
 
 
 
 
Issue: "enableCategory is not a function"
 
Cause: Using old logger API name
 
Solution: Use setCategoryLevel() instead:
 
 
 
 
Issue: "$params is not defined"
 
Cause: Trying to use store syntax with v5
 
Solution: Use function call with $derived:
 
 
 
 
Issue: "Missing './stores' specifier"
 
Cause: Trying to import from removed /stores path
 
Solution: Import from main module:
 
 
 
 
Migration Checklist
 
Before You Start
 
  • ☐ Back up your project
    •  
  • ☐ Review breaking changes list
    •  
  • ☐ Ensure tests exist for critical routes
 
Code Changes
 
  • ☐ Update Svelte to v5.0+
    •  
  • ☐ Update @keenmate/svelte-spa-router to v5.0
    •  
  • ☐ Replace all $location, $params, $querystring with function calls
    •  
  • ☐ Rename params to routeParams
    •  
  • ☐ Update Router event props to camelCase
    •  
  • ☐ Replace export let params with let { routeParams } = $props()
    •  
  • ☐ Update logger API calls
    •  
  • ☐ Update permission system configuration
    •  
  • ☐ Remove /stores import paths
 
Testing
 
  • ☐ Test all routes navigate correctly
    •  
  • ☐ Test route parameters work
    •  
  • ☐ Test protected routes and permissions
    •  
  • ☐ Test navigation guards and conditions
    •  
  • ☐ Test referrer tracking (if used)
    •  
  • ☐ Test error handling (if configured)
 
Cleanup
 
  • ☐ Remove old debug logging code
    •  
  • ☐ Update documentation
    •  
  • ☐ Review and remove unused imports
 
New Features to Explore
 
After migrating, consider adopting these new v5 features:
 
  • Category-based Logging: Fine-grained debug logging with 12 categories
    •  
  • Referrer Tracking: Automatic previous route tracking with scroll position restoration
    •  
  • goBack() Helper: Navigate to referrer with automatic scroll restoration
    •  
  • Hierarchical Routes: Automatic breadcrumb and permission inheritance
    •  
  • Global Error Handler: Comprehensive error handling with recovery strategies
    •  
  • Enhanced Permission System: Component-based unauthorized handling
    •  
  • Tree Route Structure: createHierarchy() for nested route definitions
 
See the What's New in v5 page for detailed information about all new features.
 
Getting Help
 
If you encounter issues during migration:
 
  • Check the API Reference for updated function signatures
    •  
  • Review example code in the documentation
    •  
  • Enable debug logging to troubleshoot routing issues
    •  
  • Open an issue on GitHub