sawblade
Introduction
This is a lightweight, framework-agnostic client-side JavaScript routing library.
Motivation
I was loving Svelte, but it didn't have a routing service. I knew there were other routers out there, so I began my search. My criteria included:
- Framework agnosticism (because it needed to work with a Svelte component)
- Friendly to Svelte's component lifecycle and API
- Composable routing configuration (because I like to break routing configuration apart into multiple modules)
- Hierarchical routes
- Route parameters
As you've probably already guessed, nothing matched (at least as far as I could tell), so this project was born.
Example
import { bootstrap } from 'sawblade';
import { url, navigate } from 'sawblade-hash';
import App from './App';
import Default from './Default';
import Users from './Users';
import UserList from './UserList';
import UserDetail from './UserDetail';
bootstrap(new App({ target: document.getElementById('app') }), [
{
path: '/',
render: ({ parent: app }) => new Default({ target: app.refs.outlet }),
teardown: defaultInstance => defaultInstance.teardown()
},
{
path: '/users',
render: ({ parent: app }) => new Users({ target: app.refs.outlet }),
teardown: users => users.teardown(),
children: [
{
path: '/',
render({ parent: users, params }) {
return new UserList({ target: users.refs.outlet, data: { page: params.page } });
},
update: ({ context: userList, params }) => userList.set({ page: params.page }),
teardown: userList => userList.teardown()
},
{
path: '/:id',
render({ parent: users, params }) {
return new UserDetail({ target: users.refs.outlet, data: { id: params.id } });
},
update: ({ context: userDetail, params }) => userDetail.set({ id: params.id }),
teardown: userDetail => userDetail.teardown()
}
]
}
], url, navigate);
For a more complete example, please review the example project.
Installation
Install via npm:
npm i sawblade
npm i sawblade-hash # currently the only URL provider available; supports hash-based URLs like #/blah
Then import/require via your favorite module loader.
API
bootstrap(root, routeConfiguration, url, navigate)
Activates the router.
root: The root context, i.e. the top-level element of your application. This is injected into the render function as the "parent" of any top-level routes in your route configuration.
routeConfiguration: An array of route configuration objects.
url: The current URL stream in the form of an Observable
navigate: A function that, given a URL parameter, performs a navigation within the application
route configuration: { path, render, update, teardown, children }
path: The URL of the route relative to the parent route.
render({ parent, params, navigate, path }): A function that is invoked when the route is activated.
- The supplied parent parameter is the parent context (i.e. the return value of the parent route's render function; or, for top-level routes, the root context provided as the root parameter for bootstrap.
- The supplied params parameter is an object containing the route parameters.
- The supplied navigate parameter is a function that will navigate to a URL relative to the route path
- The supplied path parameter is the route path (also used in the navigate function to resolve relative URLs)
- The return value of this function will be provided as the context parameter to the route's update function and as the only parameter to the route's teardown function.
update({ context, params, path }): A function that is invoked when the route parameters change.
- The supplied context parameter is the value returned by the corresponding render function.
- The supplied params parameter is an object containing the route parameters.
- The supplied path parameter is the route path
teardown(context): A function that is invoked when the route is de-activated. As in the update method, the context parameter is the value returned by the corresponding render function.
children: An array of child routes.