SPA router for framework-less web applications using HTML files. This library assumes you're using it in an environment, which can import HTML files as strings.
import { defineRouter } from '@dolanske/router'
import main from './routes/main.html?raw'
import user from './routes/user.html?raw'
import errorFallback from './routes/errorFallback.html?raw'
const routes = {
'/': main,
'/users': '<span>User list...</span>',
'/user/:id': {
html: user,
// In case loader throws, you can provide a fallback route to render instead
fallback: errorFallback,
async loader({ id }: { id: number }) {
return fetch(`https://swapi.dev/api/people/${id}`)
.then(r => r.json())
.then(d => d)
},
},
}
defineRouter(routes).run('#app')To create a router, call the defineRoute method in the root script of your application. This function takes in an object which contains route definitions. It returns an app instance, which contains two methods
run(domSelector)Takes in a selector for a valid DOM element, which the router will be mounted to.stop()Stops the routing
interface Route {
// Sets the title of the page
title?: string
// Content of the route, which gets rendered on navigation
html: string | Element
// Fallback should be used together with loader, to display error state
fallback?: string | Element
// If loader returns a promise, the route is not loaded until the loader
// function resolves. The returned dataset is then available through
// `onRouteResolve()` callback or when calling `getRoute()` after the route
// has loaded.
loader?: (params: any) => Promise<any>
// When page is first loaded, the router will look for a matching path, if one
// is not found, it will then check if any route is set as `default` and if it
// finds one, it loads that route
default?: boolean
// You can freely define any data which will be available on the route object
meta?: Record<string, any>
}How to navigate between pages? There are two ways.
You can add a link attribute to any <a> element like this <a href="/users" link> and it will jus work. Or you can use the navigate function.
You can navigate to a page programatically by using navigate(path). Optionally, you can provide an options object.
interface NavigateOptions {
// Append a hash parameter to the URL such as #henlo
hash?: string | boolean | number
// Query object which gets serialized into search parameters
// Such as ?hello=world&second=hello
query?: Record<string, string | number | boolean>
// These props are not saved anywhere in the URL and only available through
// `onRouteResolve()` callback or when calling `getRoute()` after the route
// has loaded.
props?: Record<string, any>
// Wether to replace the current History entry
replace?: boolean
}Whenever a route is resolved, the getRoute method will contain the resolved object, until the next route is navigated to. This is primarily useful within event listeners or async code, which isn't executed right when route is rendered.
The same object is also available in the onRouteResolve() listener.
interface ResolvedRoute extends Route {
// The actual pathname that was navigated to eg. `/users/10`
path: string
// The base path of the valid route that was navigated to eg. `/users/:id`
resolvedPath: string
// The whole html string, which is then appended to the router root element
renderedHtml: Element
// The params object, which is extracted from the path eg. `{ id: 10 }`
params?: object
// Data returned by the loader function
data: any
hash: string
query: Record<string, string>
props: object
}Every listener function returns a stopper function, which removes the provided callback from being ran.
Runs the provided callback function whenever a route is navigated to. That means if a link is clicked or a navigate() function was called.
onNavigation((serializedRoute) => {})
interface SerializedRoute extends Route {
path: string
renderedHtml: Element | null
hash: string
query: Record<string, string>
props: object
}It is possible to cancel navigation to a route, by returning false from onNavigation callback. The navigation can be async, so you can fetch what you need before deciding to cancel the navigation or not.
onNavigation(async (route) => {
if (route.meta.requiresAuth) {
const session = await getSession()
if (!session.user)
return false
}
})Runs the provided callback function whenever a route is resolved and rendered. That means once the loader function has been resolved.
onRouteResolve((resolvedRoute) => {})Returns the base router object.
Returns the router root element, which was provided during initialization
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent