Svelte 5 Migration Guide for Skeleton v2

[endigo9740]

Hey everyone, as you may be aware the Svelte 5 has now launched. We know many folks in the community are eager to update, so we wanted to provide a guide to help walk you through the process.

What to Expect

Before we begin, let's set expectations for how Svelte 5 will be utilized in either version of Skeleton:

Skeleton v2

This version of Skeleton was designed from the ground up using Svelte 4 component APIs. However, Svelte 5 offers backwards compatibility with the older APIs, which means migration should be fairly seamless. This does mean Skeleton v2 components will continue to use Svelte 4 APIs under the hood, and you will be unable to pair these with Svelte 5 features quite yet.

Skeleton v3

This version of Skeleton was designed from the ground up using Svelte 5's component APIs. Features like runes, snippets, and more. Migrating to Svelte 5 now will provide a much more streamlined process for migrating to Skeleton v3 upon release. As such, we recommend you migrate to Svelte 5 as soon as possible.

When should I migrate?

This will always be a decision that must be owned by you, as only you know the requirements and stakes of your project. That said, when you are confident and ready to migrate, we recommend creating a dedicated migration branch in your project. Then handling all updates there. That way if something goes wrong you can always drop the branch and start over.

Known Issues

Warning

There is currently one notable breaking issue when using Skeleton v2 in Svelte 5, which is related to the Tree View component. Additionally, we are expecting a delay in the v3 version of this component. So it's our current recommendation you forego this feature or implement an alternative for now.

• Breaking: Svelte v5 RC: TreeView component is non-function #2639

Perquisites

Tip

Run npm list in your terminal to check the exact versions of each dependency currently installed.

1. Create a dedicated migration branch to handle all updates
2. Migrate and update latest release of Svelte v4.
3. Migrate and update the latest release of SvelteKit v2.
4. Update to the latest release of Skeleton 2.x (2.10.3 or higher)
5. Optional but recommended: upgrade all other project dependencies to the latest versions.

Migrate to Svelte 5

When you're ready to migrate to Svelte 5, we recommend following the official documentation.

1. Run npm install -D svelte@latest
2. Follow the Svelte 5 Migration Guide (see also: Svelte 5 Migration Script)
3. Migrate your project state and logic to the new APIs
4. DONE!

Support

If you have questions, comments, or feedback about the migration process, please reach out in the comments section below or the #skeleton-next channel on Discord.

[mitkury]

Thank you, Chris!

Given that Skeleton v2 peer dependencies don't include Svelte 5 ("svelte": "^3.56.0 || ^4.0.0"), I guess it is worth mentioning that a way to install svelte 5 with skeleton 2 is to run npm install --legacy-peer-deps, a regular npm install would give an error:

npm ERR! While resolving: @skeletonlabs/[email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/svelte
npm ERR!   dev svelte@"^5.0.0" from the root project
npm ERR!   peer svelte@"^4.0.0 || ^5.0.0-next.0" from @sveltejs/[email protected]
npm ERR!   node_modules/@sveltejs/kit
npm ERR!     dev @sveltejs/kit@"^2.0.0" from the root project
npm ERR!     peer @sveltejs/kit@"^2.0.0" from @sveltejs/[email protected]
npm ERR!     node_modules/@sveltejs/adapter-static
npm ERR!       dev @sveltejs/adapter-static@"^3.0.1" from the root project
npm ERR!   4 more (@sveltejs/vite-plugin-svelte, ...)
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer svelte@"^3.56.0 || ^4.0.0" from @skeletonlabs/[email protected]
npm ERR! node_modules/@skeletonlabs/skeleton
npm ERR!   dev @skeletonlabs/skeleton@"2.10.2" from the root project
npm ERR! 
npm ERR! Conflicting peer dependency: [email protected]
npm ERR! node_modules/svelte
npm ERR!   peer svelte@"^3.56.0 || ^4.0.0" from @skeletonlabs/[email protected]
npm ERR!   node_modules/@skeletonlabs/skeleton
npm ERR!     dev @skeletonlabs/skeleton@"2.10.2" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

[endigo9740]

Thanks @mitkury, we've been making similar changes for the v3 project this week, so we'll take a look at this. Thanks for the work around for now.

[endigo9740]

@mitkury I've pushed out a new version 2.10.3 today that updates the peer dependencies so this issue should no occur. I've also updated the migration instructions above to indicated this version is required. I'll keep your comment as reference in case anyone tries to update with an older version.