svelte-spa-router

How Hash-based routing works

In hash-based routing, the current view is stored in the URL after the # symbol (the hash or fragment).

Example URLs:

• http://example.com/#/profile
• http://example.com/#/book/42

Why use Hash-based routing over HTML5 History API?

While the HTML5 History API produces cleaner URLs (e.g., http://example.com/profile), it requires a backend server to intercept and process requests for those paths to ensure that refreshing the page doesn't result in a 404 error.

Benefits of Hash-based routing:

• No server configuration required: Works perfectly with static file hosting.
• Simpler deployment: Ideal for fully-static SPAs.
• Reliable navigation: Users can share links and refresh pages without needing a specialized server setup.

Note: This approach is best suited for applications where SEO is not a primary concern, such as apps behind an authentication wall.

Starting with version 3.0, svelte-spa-router supports code splitting by using the import() construct for components. This allows bundlers like Vite, Rollup, and Webpack to split your application into smaller chunks, reducing the initial bundle size.

To implement this, you must use the wrap method from svelte-spa-router/wrap. In your route configuration, instead of passing the component directly, pass a wrap object where the asyncComponent property is a function definition that returns the dynamic import.

Warning: Do not invoke the import immediately. Use asyncComponent: () => import('./Component.svelte') instead of asyncComponent: import('./Component.svelte').

import {wrap} from 'svelte-spa-router/wrap'

const routes = {
    '/': Home,

    // Wrapping the Author component
    '/author/:first/:last?': wrap({
        asyncComponent: () => import('./routes/Author.svelte')
    }),

    // Wrapping the Book component
    '/book/*': wrap({
        asyncComponent: () => import('./routes/Book.svelte')
    }),

    // Catch-all route last
    '*': NotFound,
}

svelte-spa-router provides a use:active action to automatically apply CSS classes to links based on the current route. This is useful for styling navigation menus where the current page link needs to look different.

You can use the action in three ways:

1. With a configuration object: Specify a custom path (supporting wildcards or regex), a className for active states, and an inactiveClassName for non-active states.
2. With a shorthand string/regex: Passing a single string or regular expression will be treated as the options.path.
3. With no arguments: Uses the link's href as the path and the default active class name.

Note on Styling: Because the router adds the class directly to the element, you must use the :global() modifier in your Svelte <style> block to ensure the styles are applied to the link.

<script>
import {link} from 'svelte-spa-router'
import active from 'svelte-spa-router/active'
</script>

<style>
/* Style for "active" links. 
Need to mark this :global because the router adds the class directly */
:global(a.active) {
    color: red;
}
</style>

<a href="/hello/user"
  use:link
  use:active={{path: '/hello/*', className: 'active', inactiveClassName: 'inactive'}}>
  Say hi!
</a>

Route pre-conditions (or "route guards") are functions executed before a route is loaded. They are defined in the options.conditions array within wrap.

Execution Logic:

• Functions are executed in order.
• If a function returns true, the router proceeds to the next condition or loads the route.
• If a function returns false, the router stops and does not load the route.
• Pre-conditions can be async (e.g., for checking authentication via a network request).

The detail object: Each pre-condition receives a detail object containing:

• detail.route: The matched route definition.
• detail.location: The current path.
• detail.querystring: The current querystring.
• detail.userData: The custom data attached via wrap.

<!-- App.svelte -->
<Router {routes} {onConditionsFailed} />

<script>
import Router from 'svelte-spa-router'
import {wrap} from 'svelte-spa-router/wrap'
import Lucky from './Lucky.svelte'

const routes = {
   '/lucky': wrap({
      component: Lucky,
      userData: { hello: 'world' },
      conditions: [
         (detail) => {
            return (Math.random() > 0.5)
         },
         async (detail) => {
            const response = await fetch('/user/profile')
            const data = await response.json()
            return data.isAdmin
         }
      ]
   })
}

function onConditionsFailed(detail) {
   console.error('onConditionsFailed', detail)
   if (detail.userData.hello === 'world') {
      // Perform fallback action
   }
}
</script>