Handling breaking changes in SvelteKit pre-1.0

4 min read Original article ↗

Thilo Maier •

Last modified:

This post is obsolete. To get started with SvelteKit, go to the SvelteKit docs.

In August 2022, the SvelteKit team led by Rich Harris introduced a series of refactorings in preparation for SvelteKit 1.0. The most significant changes were a complete overhaul of SvelteKit’s router and load API, and the redesign resulted in several breaking changes.

Why breaking changes?

SvelteKit follows semantic versioning, and the specification states that

4. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

While SvelteKit is pre-1.0, any release can include breaking changes. Despite this caveat, SvelteKit was widely adopted and used in production. Breaking changes happened occasionally, but they were rare. Consequently, the wider Svelte community (myself included) assumed that SvelteKit was ready for production. After a summer of breaking changes, I realized that considering SvelteKit stable enough for production was premature.

Now that many developers run SvelteKit in production, what is the best way to deal with all the breaking changes?

Upgrading to recent SvelteKit versions with breaking changes

If you have a SvelteKit app in production that you have not upgraded in a while, you should not try to upgrade directly to the latest version. Here are some milestone releases you can use for your upgrade path:

SvelteKit 1.0.0-next.377

1.0.0-next.377 includes a breaking change in which you need to uppercase endpoint methods.

SvelteKit 1.0.0-next.405

1.0.0-next.405 is the last version before the overhaul of SvelteKit’s router. Make sure your site runs without issues on this version.

SvelteKit 1.0.0-next.414

1.0.0-next.414 is the last version before another significant breaking change. Now it’s time to read up on the changes released in 1.0.0-next.406. Read one of these two posts:

Then read the first comment in Rich Harris’s migration guide and run the migration script:

npx svelte-migrate routes

The script automates most of the work. It handles renaming files and leaves @migration comments with links to related comments in the migration guide. You should review all migration comments and proposed changes. Depending on the size of your site, this can take a couple of hours.

SvelteKit 1.0.0-next.415

1.0.0-next.415 removes the session object. You can skip this version if you do not use the session object. If you use the session object, you need to read this discussion on why it has been removed and how to replace it. This is a non-trivial upgrade.

SvelteKit 1.0.0-next.432

1.0.0-next.432 removes named layouts in favor of groups. Check out this migration guide. If you do not use named layouts, skip to the next version.

SvelteKit 1.0.0-next.455

1.0.0-next.450 requires upgrading Vite in your package.json:

"vite": "^3.1.0-beta.1"

1.0.0-next.455 overhauls prerendering. Read the docs on page options to find out what has changed.

SvelteKit 1.0.0-next.463

Finally, 1.0.0-next.463 fixes a peer dependency warning introduced with Vite 3.1.0-beta.1.

Conclusion

Fixing all recent breaking changes can feel like a daunting task, and it probably is if you have a large website. If you have a SvelteKit app in production, there is not much you can do other than upgrade to new versions as they are released.

This post demonstrates that you do not have to upgrade to every new release and that you can skip upgrades when they contain only patch changes. But the longer you wait, the more breaking changes will accumulate and the more complex upgrades will become.

How many more breaking changes will there be? I don’t know. But I hope the SvelteKit team is on the home stretch toward 1.0.