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 or Webpack.
You can install svero via npm:
npm install --save svero
Usage
The usage is super simple:
<!-- ./App.svelte -->
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 asrouter.params._
like other params.
A component loaded by <Route>
receives a property with route details:
<!-- ./pages/About.svelte -->
Additional properties are passed to the mounted component, e.g.
Also, you can pass an object:
Route
props are omitted, but all remaining ones are passed toTest
.
Routes can also render any given markup when they're active, e.g.
It works!
You can access
router
within<slot />
renders by declaringlet:router
on<Router />
or<Route />
components (see below).
If you're building an SPA or simply want to leverage on hash-based routing for certain components try the following:
Info: {JSON.stringify(router.params)}
Standard anchors and <Link />
components will work as usual:
View README.md
Declaring a component <Route path="#" />
will serve as fallback when location.hash
is empty.
Nesting
You can render svero
components inside anything, e.g.
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<Router />
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
<Route />
withoutpath
will render only if<Router path="..." />
is active!
Note that all
<Router />
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.
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).
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 <Link>
component that overrides <a>
elements:
Hello!
The difference between <Link>
and <a>
is that it uses pushState
whenever possible, with fallback to <a>
behavior. This means that when you use <Link>
, 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. whenlocation.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 <Link>
: It will always try to use pushState
for better performance, fallbacking to a full page redirect if it isn't supported.
Usage: