Migrate to SvelteKit's New Routing System

Viewed 839

Don't know about you, but I've been hearing about this new routing system in SvelteKit. I first heard about this with the +error.svelte file that I found here on the official docs. Not soon enough, I've also seen the other files like the __layout.svelte file having a + sign in front of it's filename like this: +layout.svelte on the docs.

So I've been wondering:

  • How do I migrate from the SvelteKit's old routing system to this updated routing system?
  • If possible, how to let SvelteKit do it automatically?
  • What's the importance of this new routing system?
2 Answers
  1. Before installing the new version, update to the most recent version before these changes — @sveltejs/kit@next.405 — ensuring that your app works with that version before running the migration.
  2. Run the following command:

npx svelte-migrate routes

By running the command and hitting y, you should see this:

enter image description here

  1. Done! It's up to you if you want to follow the recommended next steps, but I recommend you to take on these steps. :)

The following is supplementary information.

Reading the following lines is optional.

I found some good material to come up with the solution above:

Migration Guide

Quoting Rich Harris from this page:

New versions of SvelteKit include a design overhaul that will require some changes to your app.

To begin migrating your app, run the following command:

npx svelte-migrate routes

You will need to do this before installing the new version! We recommend updating to the most recent version before these changes — @sveltejs/kit@next.405 — and ensuring that your app works with that version before running the migration.

This will rename files inside your routes folder (see this comment to learn more about the changes), migrate some of the changes automatically and annotate your code with errors that link back to this page and tell you what needs to be manually updated. You can find these errors by searching your codebase for @migration.

Reason of change

One of the most important reasons I've read is this one, again quoting Rich Harris:

There are multiple ways to express a route. src/routes/foo.svelte and src/routes/foo/index.svelte are equivalent, and having two ways to do things is always a source of confusion. Each has downsides — too many index.svelte files open in your editor gets confusing, but foo.svelte makes it awkward to colocate related files. I frequently find myself moving foo.svelte to foo/index.svelte as the route becomes more complex (e.g. it needs a dedicated error page, or it gains a child route, or I need to break something out into a separate component, or it needs a page endpoint, and so on). These changes are costly and annoying, and I always kick myself for not just always using folders.

You may read all the other good reasons on this link.

I am still a beginner at web development so need the exact steps spelled out. Here are the commands I actually ran to migrate my simple project:

Update to the version before the routing changes:

npm install @sveltejs/kit@1.0.0-next.405

Build your project and fix any issues until it works. My project was simple, so the only changes were to package.json and the project still built and ran fine. Commit those changes.

Run the migrate script:

npx svelte-migrate routes

That script will run and then print the following instructions:

  1: git commit -m "svelte-migrate: renamed files"
  2: Review the migration guide at https://github.com/sveltejs/kit/discussions/5774
  3: Search codebase for "@migration" and manually complete migration tasks
  4: git add -A
  5: git commit -m "svelte-migrate: updated files"

After running that script my project would build but does not work. My project was too simple to have any "@migration" comments. Presumably, you need to make the migration changes following the guide without really knowing if they worked or not.

Finally, install the version with the new routing changes:

npm install @sveltejs/kit@1.0.0-next.406

Without any additional changes in my project, my project built and ran successfully. Again, only the package.json changed and I committed it.

Related