Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kazzkiq/svero

⚠️ ⚠️ (DEPRECATED) A simple router for Svelte 3
https://github.com/kazzkiq/svero

Last synced: about 1 month ago
JSON representation

⚠️ ⚠️ (DEPRECATED) A simple router for Svelte 3

Awesome Lists containing this project

README 

        
⚠️⚠️ THIS LIBRARY IS DEPRECATED AND SHOULD NOT BE USED IN NEW PROJECTS ⚠️⚠️



⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️


⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️



⚠️⚠️ MORE DETAILS [HERE](https://github.com/kazzkiq/svero/issues/68). ⚠️⚠️



⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️


⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️



[![npm version](https://badge.fury.io/js/svero.svg)](https://www.npmjs.com/package/svero)

[![Build Status](https://travis-ci.org/kazzkiq/svero.svg?branch=master)](https://travis-ci.org/kazzkiq/svero)





  svero (Svelte Router): A simple router for Svelte 3.




## First things first



svero is intented to be used in SPA (Single Page Applications) making usage of `pushState` and History API. We're assuming that you already know how to configure your front-end server (being it dev or production) to serve all path requests to `index.html`.



If you're not familiar with the terms SPA, `pushState` or History API, you should probably be reading these first:



http://krasimirtsonev.com/blog/article/deep-dive-into-client-side-routing-navigo-pushstate-hash


https://css-tricks.com/using-the-html5-history-api/


https://diveinto.html5doctor.com/history.html


https://developer.mozilla.org/pt-BR/docs/Web/API/History



## Installation



Since it's exported in CommonJS format, you should be using it with a module bundler such as [Rollup](https://github.com/sveltejs/template/tree/v3) or Webpack.



You can install svero via npm:



```

npm install --save svero

```



## Usage



The usage is super simple:



```html



  import { Router, Route } from 'svero';



  import Index from './pages/Index.svelte';

  import About from './pages/About.svelte';

  import Employees from './pages/Employees.svelte';



  let employees = [{ id: 1, name: 'Bill'}, { id:2, name: 'Sven' }];



  

  

  

  

    

  



```



The `*` wildcard simply works as a fallback. If a route fails to meet any other path, it then loads the path with the `*`. If there is no wildcard route and the route did not meet any other path, nothing is loaded.



Your custom props can be passed by putting your component in the Route `slot` (Employees example above).



Paths with parameters (`:param`) are passed to components via props: `router.params`.



> Parameters like `*param` will capture the rest of segments. You can access them as `router.params._` like other params.



A component loaded by `` receives a property with route details:



```html



  export let router = {};



  // Those contains useful information about current route status

  router.path; // /test

  router.route; // Route Object

  router.params; // /about/bill/123/kansas { who: 'bill', where: 'kansas' }



```



Additional properties are passed to the mounted component, e.g.



```html



```



Also, you can pass an object:



```html



```



> `Route` props are omitted, but all remaining ones are passed to `Test`.



Routes can also render any given markup when they're active, e.g.



```html



  
It works!



```



> You can access `router` within `` renders by declaring `let:router` on `` or `` components (see below).



If you're building an SPA or simply want to leverage on hash-based routing for certain components try the following:



```html



  
Info: {JSON.stringify(router.params)}



```



Standard anchors and `` components will work as usual:



```html

View README.md

```



Declaring a component `` will serve as fallback when `location.hash` is empty.



### Nesting



You can render `svero` components inside anything, e.g.



```html



  

    

      Routing:

      

        {router.params.bar}!

      

      Foo

      

        

          
Not found: {router.params._}


          {router.failure}

        

      

      

        

          [...]

          not found?

          A

          C

          {JSON.stringify(router.params)}

        

      

    

  



```



Properties determine how routing will match and render routes:



- Use the `nofallback` prop for telling `` to disable the _fallback_ mechanism by default

- Any route using the `fallback` prop will catch unmatched routes or potential look-up errors

- Use the `exact` prop to skip this route from render just in case it does not matches

- A `` without `path` will render only if `` is active!



> Note that all `` paths MUST begin from the root as `/sub` and `/sub/nested` in the example.



### Redirects



Sometimes you just want a route to send user to another place. You can use the `redirect` attribute for that.



A redirect should always be a string with a path. It uses the same pattern as `path` attribute. For a redirect to run, there must be a Route with the equivalent path.



```html



  

  



```



### Conditions



If you need to meet a condition in order to run a route, you can use the `condition` attribute. Conditions can also be used with `redirect` for graceful route fallback.



A condition should be either `boolean` or a function returning `boolean`. There is no support for asynchronous conditions at the moment (so keep it simple).



```html



  



```



Think of it as a simpler middleware. A condition will run *before* the route loads your component, so there is no wasteful component mounting, and no screen blinking the unwanted view.



### Link Component



There is also an useful `` component that overrides `` elements:



```html

Hello!

```



The difference between `` and `` is that it uses `pushState` whenever possible, with fallback to `` behavior. This means that when you use ``, svero can update the view based on your URL trigger, without reloading the entire page.



> Given `href` values will be normalized (on-click) if they don't start with a slash, e.g. when `location.pathname === '/foo'` then `#bar` would become `/foo#bar` as result.



### navigateTo()



In some cases you want to navigate to routes programatically instead of letting user click on links. For this scenario we have `navigateto()` which takes a route as parameter and navigates imediatelly to said route.



`navigateTo()` receives the same treatment as ``: It will always try to use `pushState` for better performance, fallbacking to a full page redirect if it isn't supported.



Usage:



```html



  import { onMount } from 'svelte';

  import { navigateTo } from 'svero';



  onMount(() => {

    if (localStorage.getItem('logged')) {

      navigateTo('/admin');

    }

  });



```



### Webpack issues



If you're having trouble with Webpack failing to load svero, please replace the following rule (in Svelte rule):



```js

exclude: /node_modules/,

```



with:



```js

exclude: /node_modules\/(?!(svero)\/).*/,

```



More information [here](https://github.com/kazzkiq/svero/issues/23).