svelte-history-router
TypeScript icon, indicating that this package has built-in type declarations

1.0.0-beta.16 • Public • Published

Svelte History Router

A high performance history based router using History API.

Svelte v3 npm download Bundle Size LICENCE

🔨 Installation

npm install svelte-history-router

or

yarn add svelte-history-router

Why another Router?

  • Most of the router implementation are pretty naive, they use regex under the hook, which may have bad performance on routing especially with huge routing tree.
  • Most of the router using context api, which may required some setup when we use with vite or snowpack.

Features

  • History based routing
  • TypeScript as First Class Citizen
  • Lightweight
  • High performance
  • Ship with multiple output formats (commonjs, iife, esmodule)
  • No extra dependency
  • Reactive functions
  • Simple and configurable

📝 How to use?

Define your routes

Each route is a normal Svelte component, with the markup, scripts, bindings, etc. Any Svelte component can be a route.

The route definition is just a JavaScript dictionary (object) where the key is a string with the path (including parameters, etc), and the value is the route object.

For example:

import Home from "./Home.svelte";
import AboutUs from "./AboutUs.svelte";
import MyProfile from "./MyProfile.svelte";
import MyInfo from "./MyInfo.svelte";
import MyPage from "./MyPage.svelte";
import NotFound from "./NotFound.svelte";

const routes = {
  // Exact path
  "/": Home,
  "/about-us": AboutUs,

  // Using named parameters, with last being optional
  "/me/:name/profile": MyProfile,
  "/me/:name/info": MyInfo,

  // Wildcard parameter
  "/me/*": MyPage,

  // Catch-all
  // This is optional, but if present it must be the last
  "*": NotFound,
};

Routes must begin with / (or * for the catch-all route). When you using * wildcard route, you cannot place route path after *.

The order doesn't matters! Because the routing is follows the following priority :

  1. Exact match
  2. Placeholder match
  3. Wildcard match

Include the router view

To display the router, in a Svelte component (usually App.svelte), first import the router component. Then, display the router anywhere you'd like by placing the component in the markup. For example:

<script>
    import Router from 'svelte-history-router';
    import routes from './routes.ts';
</script>

<body>
    <Router {routes}/>
</body>

Navigating between pages

You can navigate between pages using anchor () tag with svelte action link. For example:

<script>
    import { link } from 'svelte-history-router';
</script>

<a use:link href="/me/profile">
    <p>The Biggest Princess</p>
</a>

Futhermore, you can navigate between pages programmatically too:

import { push, pop, replace } from "svelte-history-router";

// The push(url) method navigates to another page, just like clicking on a link
push("/me/joker/profile");

// The pop() method is equivalent to hitting the back button in the browser
pop();

// The replace(url) method navigates to a new page, but without adding a new entry in the browser's history stack
// So, clicking on the back button in the browser would not lead to the page users were visiting before the call to replace()
replace("/me/profile");

These methods can be used inside Svelte markup too, for example:

<button on:click={() => push('/page')}>Go somewhere</button>

The push, pop and replace methods perform navigation actions only in the next iteration ("tick") of the JavaScript event loop. This makes it safe to use them also inside onMount callbacks within Svelte components.

URL

You can get the page url information (it's an URL object) from the $url readable store. This is a Svelte store, so it can be used reactively too.

<script>
    import { url } from 'svelte-history-router';
    const { searchParams } = $url;
</script>

<p>The page query string is : {searchParams.toString()}</p>

Parameters

You can get the page parameters from the $params readable store. This is a Svelte store, so it can be used reactively too.

<script>
    import { params } from 'svelte-history-router';
</script>

<p>The page parameters is : {JSON.stringify($params)}</p>

Sponsors

WeTix

License

svelte-history-router is 100% free and open-source, under the MIT license.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers

GitHub NPM

Inspired by radix-router and svelte-spa-router

Readme

Keywords

none

Package Sidebar

Install

npm i svelte-history-router

Weekly Downloads

1

Version

1.0.0-beta.16

License

MIT

Unpacked Size

178 kB

Total Files

16

Last publish

Collaborators

  • bassemsab
  • mohamadharith