@svelte-router/kit

Hash router for Sveltekit projects

This is an extension package for webJose's Svelte Router, and enables the use of the router in hash mode in Sveltekit projects.

Why Would I Need This?

Sveltekit has an excellent file-based router. You should always stick to the built-in router for routing your application. However, as with every other router in existence, you can only do path routing or hash routing, but not both.

webJose's Svelte Router router was born to break this barrier: This SPA router can do path and hash routing simultaneously. However, this is a router for SPA's and PWA's that render on the client. It was not designed for SSR scenarios. After all, Sveltekit has routing capabilities included.

But what if you wanted to do hash routing on top of Sveltekit's path routing? You can today, with this router extension.

Useful Scenarios

1. You could show a complex dialog box that is driven by hash routing.
2. You could mount your application as a micro-frontend that routes with multiple paths in the hash fragment.
3. You could drive your tabs components with individual named hash paths (this is demonstrated in this repository's demo project).

Quickstart

1. Install the package

   npm install @svelte-router/kit # This also installs the @svelte-router/core main package

2. Initialize the library. Ideally, in the root +layout.svelte component:

   <script lang="ts">
       import { init } from "@svelte-router/kit";
   
       init(/* options */);
   </script>

3. Add routers, routes and links for hash navigation as you please. Note that these are still imported from the core package, @svelte-router/core.
4. EXCEPTION: Don't use the core package's Fallback component. Use this package's KitFallback component for fallback content to avoid flashes of unwanted content when rendering on the server.

⚡ Attention!

There might be a bug in Svelte or Sveltekit. Situation: Just importing init from @svelte-router/kit triggers error rune_outside_svelte on the trace.svelte.js file in the @svelte-router/core package. To overcome this, just add { ssr: { noExternal: ["@svelte-router/core"] }} to Vite's configuration.

If this becomes unneeded, this warning will be removed; if this is just the reality of things, this warning will become one more step in the quickstart.

Limitations

1. Path routing is disallowed.

Generally speaking, you need to understand the core router, so have handy its online documentation.