esroute
v0.9.1
Published
A small efficient framework-agnostic client-side routing library, written in TypeScript.
Downloads
17
Readme
esroute
A small efficient framework-agnostic client-side routing library, written in TypeScript.
It is currently under development and API might slightly change.
Features
Those features may be the ones you are looking for.
- 🌈 Framework agnostic
- 🧭 Concise navigation API
- 🕹 Simple configuration
- ✅ Typesafe value resolution
- 🏎 Fast startup and runtime
- 🛡 Route guards
- 🦄 Virtual routes
🌈 Framework agnostic
Esroute is written with no external dependencies, so it does not require you to use a library.
🧭 Concise navigation API
Navigation with esroute is straight-forward.
There is a go()
method on the router instance.
Examples:
// Navigate to some page
router.go("/some/path", { search: { foo: "bar" }, state: 42 });
// Update search params, keeping previous path and state. Will use history.replaceState() by default.
router.go((prev) => ({
search: { foo: "baz" },
}));
🕹 Simple configuration
A configuration can look as simple as this:
import { createRouter } from "esroute";
const router = createRouter({
routes: {
"": ({ go }, next) => next ?? go("/foo"),
foo: () => load("routes/foo.html"),
nested: {
"": load("routes/nested/index.html"),
"*": ({ params: [param] }) => load("routes/nested/dynamic.html", param),
},
},
});
router.onResolve(({ value }) => render(value));
router.init();
You can compose the configuration as you like, which allows you to easily modularize you route configuration:
const router = createRouter({
routes: {
"": ({ go }) => go("/mod1"),
mod1: mod1Routes,
merged: {
...mod2Routes,
...mod3Routes,
},
},
});
✅ Typesafe value resolution
The router can be restricted to allow only certain resolution types.
const router = createRouter<string>({
routes: {
"": () => "some nice value",
async: loadString(),
weird: () => 42, // TS Error
},
});
🏎 Fast startup and runtime
esroute comes with no dependencies and is quite small.
The route resolution is done by traversing the route spec that is used to configure the app routes (no preprocessing required). The algorithm is based on simple string comparisons (no regex matching).
🛡 Route guards
You can prevent resolving routes by redirecting to another route within a guard:
const router = createRouter({
routes: {
members: {
"?": async ({ go }) => (await isLoggedIn()) || go("/login"),
...memberRoutes,
},
},
});
In the example above, a logged in user will see the profile and a logged-out user will see the login page instead.
Another example:
const router = createRouter({
routes: {
"*": {
"?": async ({ go, params: [id] }) =>
(await exists(id)) || go("/not-found"),
...someRoutes,
},
},
});
🦄 Virtual routes
When route resolution is done, all virtual routes (""
) on the path to the leaf are collected and then rendered from leaf to root.
This allows creating various szenarios. Here are some examples:
Composed rendering
const router = createRouter({
routes: {
foo: {
"": ({}, next) => (next ? `foo${next}` : "foo"),
bar: () => `bar`,
},
},
});
In this case the route /foo
will resolve to "foo"
and the route /foo/bar
will resolve to foobar
. With this pattern you can implement index routes and frames.
Anonymous grouping of routes
In some cases you might want to attach rendering af a common frame or a guard to a set of routes without placing them on a separate named parent route. This is where virtual routes come into play:
const router = createRouter({
routes: {
"": {
"": ({ go }, value) => (loggedIn ? value ?? renderIndex() : go("/login")),
...memberRoutes,
},
login: () => renderLogin(),
},
});
In this sczenario we have the memberRoutes
next to the /login
route.
Router configuration
The createRouter
factory takes a RouterConf
object as parameter.
The Routes
Example:
const routes: Routes = {
"": ({ go }, value) => (isLoggedIn || value) ?? go(["login"]),
x: resolveX,
nested: {
"": resolveNestedIndex,
y: resolveY,
level2: {
z: resolveZ,
},
"*": {
foo: ({ params: [myParam] }) => resolveFoo(myParam),
},
},
};
The RouterConf
RouterConf
provides some router-specific configuration:
interface RouterConf<T> {
routes?: Routes<T>;
notFound?: Resolve<T>;
noClick?: boolean;
onResolve?: (resolved: Resolved<T>) => void;
}
RouterConf.routes
The routes configuration.
You may modify this object to change the routes.
Be sure to call router.init()
after the current route is configured.
RouterConf.notFound
A fallback resolve funuction to use, if a route could not be found.
By default it redirects to the root path '/'.
RouterConf.noClick
Whether the click handler for anchor elements shall not be installed. This might make sense, if you want to take more control over how anchor clicks are handled.
RouterConf.onResolve
A callback that is invoked whenever a route is resolved.