Skip to content

API reference

Everything here is exported from @spock/router. Dev tools use a separate entry point, @spock/router/devtools, which apps shouldn’t import.

function createRouter<const T extends RouteDef>(tree: T & CheckTree<T>): Router<T>;

Builds the router from a route tree. Route names come from the tree’s keys, params from its paths, and each route’s node from its own data selector, or its nearest bound ancestor’s. The tree is checked as a whole: see What’s checked. See The route tree.

One route in the tree.

type RouteDef = {
path?: string;
component?: RouteComponent;
notFound?: RouteComponent;
data?: (params) => object | undefined;
children?: Record<string, RouteDef>;
};

What createRouter returns. Pass it to RouterProvider, and register its type with Register. Its properties are internal.

An interface to augment with your router’s type, so route names, params and nodes are typed everywhere:

declare module "@spock/router" {
interface Register {
router: typeof router;
}
}
<RouterProvider router={router} />
<RouterProvider router={router} initialPath="/acme/projects/web" />

Renders the app. Put it at the root, once. Each navigation by Link scrolls to the top; back and forward leave the scroll position to the browser.

With initialPath, it renders that URL from memory instead of the address bar, so links navigate without touching the browser’s history. Use it to render a page in a given state outside the app: a story, a test, a static export.

<Link to="org.project.document" params={{ documentId: d.id }} exact className="...">...</Link>
Prop Type What it does
to RouteName The target route, by name.
params Partial<ParamsOf<to>> Params to add to, or override, the current route’s.
exact boolean Active only on this exact route, not on its children.
className string
children ReactNode

Throws when it renders if the merged params are missing one the target needs. See Links.

Renders the matched child route. Put one in every layout.

If a route throws while it renders, for example a Link missing a param, the error shows in that route’s place. The layouts above it keep working, and the error clears on the next navigation.

function node<T extends object>(): {
page: (component: RouteComponent) => Page<T>;
useData: (options?: { sync?: boolean }) => Snapshot<T>;
useDataProxy: () => T;
};

Hooks for a node of shape T, and page, which marks a route component as needing one. See Pages.

function useData<T extends object>(options?: { sync?: boolean }): Snapshot<T>;

A read-only, reactive snapshot of the node of the route that rendered this component. Pass { sync: true } for controlled inputs. Throws if no route above the component is bound.

Nothing checks T against the route. In pages and portable components, use the useData from node<T>() instead.

function useDataProxy<T extends object>(): T;

The live valtio proxy for the route’s node. Mutate it to write. Throws if no route above the component is bound. As with useData, prefer the one from node<T>().

function useRouteInfo(): { name: RouteName; boundAt: RouteName | undefined };

The route that rendered this component, and the route its node was bound at. boundAt is undefined when no route above it is bound.

Type What it is
RouteName Every route name in the registered tree, such as "root" | "org" | "org.members".
ParamsOf<N> All params of route N, its ancestors’ included, as strings.
NodeOf<N> The node route N is bound to, by its own data or inherited.
RouteComponent A component that renders with no props: () => ReactNode.
Page<T> A route component that needs a node of shape T. Made with node<T>().page.
LinkProps<N> Link’s props, for a link to route N.