svelte-dk-router

An efficient, easy-to-use router for Svelte

• Installation
• Quick Start
• API
  • setRoutes
  • SView
  • SLink
  • route
  • routeStore
  • routeChart
  • routeChartStore
  • routeProps
  • push
  • replace
  • beforeEach
  • afterEach
  • setQuery
  • setParams
  • location properties
  • router-active

Installation

npm i svelte-dk-router

or...

yarn add svelte-dk-router

Quick Start

First set your routes:

import { setRoutes } from 'svelte-dk-router'
import home from './views/home.svelte'
import about from './views/about.svelte'
import origins from './views/nested/origins.svelte'
import future from './views/nested/future.svelte'
import more from './views/nested/more.svelte'
import blog from './views/blog.svelte'
import fallback from './views/fallback.svelte'

const routes = [
    {
        name: 'Home',
        // Update page title
        title: 'Home',
        path: '/',
        component: home,
        meta: {
            name: 'dan'
        }
    },
    {
        // If no name passed,
        // defaults to components' name
        title: 'About',
        path: '/about',
        component: about,
        children: [
            {
                name: 'Default About',
                // Pass an empty path to display a default child
                path: '',
                component: future,
                children: [
                    {
                        title: 'More | About',
                        // Full-path: /about/more
                        path: '/more',
                        component: more
                    }
                ]
            },
            {
                title: 'Origins | About',
                path: '/origins',
                component: origins,
                children: [
                    {
                        name: 'More About',
                        title: 'More | About',
                        // Full-path: /about/origins/more
                        path: '/more',
                        component: more
                    }
                ]
            }
        ]
    },
    {
        title: 'Blog',
        // Named-params are specified with a colon
        path: '/blog/:id/:name',
        component: blog
    },
    // Define your fallback last
    // Must have a path of '(*)'
    {
        name: 'Fallback',
        title: '404',
        path: '(*)',
        component: fallback
    }
]

setRoutes(routes)
// Or, for hash-based routing:
setRoutes(routes, true)

Then, use the view component:

<script>
    import { SView } from 'svelte-dk-router';
</script>

<SView />

Links to navigate:

<script>
    import { SLink } from 'svelte-dk-router';

    let params = { id: '1', name: 'dan' };
    let query = { id: '1', name: 'dan' };
    let props = { some: 'extra information' };
</script>

<SLink name={'Home'}>Home</SLink>
// Using props allows you to pass any data to the next page
<SLink path={'/about'} {query} {props}>About</SLink>
<SLink path={'/blog'} {params} replace={true}>Blog</SLink>
// Navigate to a nested route
<SLink name={'More About'}>More Info</SLink>
// Full paths are also supported
<SLink path={'/about/origins/more'}>More Info</SLink>

Lastly, don't forget to set your Rollup config to handle SPA's with -s:

"scripts": {
    ...
    "start": "sirv public -s",
}

API

NOTE: All navigations are asynchronous.

setRoutes(routes: array[object], hashMode?: boolean)

Set your routes and optionally set to hashMode (prepends all routes with /#).

If no name is set for a route, the components' name is used instead.

<SView />

The main view for your routes.

You can nest any number of views within your set components.

<SLink />

Link to each route. name or path are required, optional query, params (if defined), props and replace.

Dispatches a navigation event which returns an object with the success status and, if successful, the route being navigated to, else the error which was thrown.

replace defaults to false, meaning pushState is used instead of replaceState.

Example:

<SLink
    name={string}
    path={string}
    query={object}
    params={object}
    props={any}
    replace={boolean}
    on:navigation={e => console.log(e.detail)} // e.detail = result
>
    Slot for any link content
</SLink>

route

An object containing all information on the current route.

Example:

{
    component: class Home,
    // An array of route-names matching the current path
    crumbs: ["Home"],
    // Current route-depth
    depth: 1,
    fullPath: "/",
    fullRegex: /^\/?$/i,
    meta: { name: "dan" },
    name: "Home",
    path: "/",
    query: { id: "1" },
    regex: /^\/?$/i,
    rootPath: "/",
    title: "Home"
}

routeStore

A readable Svelte store which, through the .subscribe method, returns the current route whenever it's updated.

routeChart

An object containing a chart of all routes from the parent-route, down to the current route.

Example:

// Navigating to '/about' displays the default child route
1: {title: "About", path: "/about", children: Array(2), name: "About", component: ƒ, …}
2: {name: "Default About", path: "", children: Array(1), parent: {…}, component: ƒ, …}

routeChartStore

A readable Svelte store which, through the .subscribe method, returns the current route-chart whenever it's updated.

routeProps

A variable containing any data passed as props through <SLink />, push() or replace().

Resets to null on route change.

push(identifier: string, routeData?: object): current route

Programmatically changes the route using window.history.pushState().

identifier has to be the name or path of a route.

Returns a promise which can be chained:

await push('/')
    .then(newRoute =>  /* Resolved */)
    .catch(err =>  /* Rejected */);

Available properties you can pass:

await push('Blog', {
    params: { id: '1', name: 'dan' },
    query: { postTitle: 'how-to-use-svelte-dk-router' },
    props: { post: blogPost }
})

replace(identifier: string, routeData?: object): current route

The same as push(), except, uses window.history.replaceState() instead.

beforeEach((to, from, setProps) => {})

Navigation guard to run before each route-change.

to contains all data for the route navigating to, from all data of the current route.

setProps allows you to set the value of routeProps (props in afterEach).

Note: Props can only be set once per navigation.

If async/await is used, the callback will be awaited before navigating.

If a redirect is initiated, the original navigation is cancelled and replaced with the redirect.

To cancel any navigation, return false.

Note: Set your navigation-guards before you call setRoutes, else, they won't run on page-load.

afterEach((to, from, props) => {})

Navigation guard to run after each route-change.

to contains all data for the route navigated to, from all data of the previous route.

props is essentially an alias for the routeProps import.

Note: Set your navigation-guards before you call setRoutes, else, they won't run on page-load.

setQuery(query: object, update?: boolean, replace?: boolean): current route

Programmatically set query params.

If update is set to true, replaces/adds to existing query.

Defaults to window.history.replaceState, if replace is set to false, uses window.history.pushState instead.

Returns a promise which resolves with the updated route data.

Example:

await setQuery({ new: 'query' })
    .then(updatedRoute => /* Resolved */)
    .catch(err => /* Rejected */);

setParams(params: object, replace?: boolean): current route

Programmatically update named-params. Params must be correctly defined for the current route.

Defaults to window.history.replaceState, if replace is set to false, uses window.history.pushState instead.

Returns a promise which resolves with the updated route data.

location properties

You can also import variables for each property of window.location:

import {
    hash,
    host,
    hostname,
    href,
    origin,
    pathname,
    port,
    protocol,
    search
} from 'svelte-dk-router'

These variables update on each route change, ensuring simplicity and parity throughout your application.

.router-active

Any <SLink /> which matches the current-route/exists in the current-route heirarchy, has the class router-active applied.

In the spirit of a11y, the attribute aria-current="page" is also set using this method.

Contributions welcome.