API reference
Everything here is exported from @spock/router. Dev tools use a separate entry point,
@spock/router/devtools, which apps shouldn’t import.
Router
Section titled “Router”createRouter(tree)
Section titled “createRouter(tree)”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.
RouteDef
Section titled “RouteDef”One route in the tree.
type RouteDef = { path?: string; component?: RouteComponent; notFound?: RouteComponent; data?: (params) => object | undefined; children?: Record<string, RouteDef>;};Router
Section titled “Router”What createRouter returns. Pass it to RouterProvider, and register its type with Register. Its properties are
internal.
Register
Section titled “Register”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; }}Components
Section titled “Components”RouterProvider
Section titled “RouterProvider”<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.
Outlet
Section titled “Outlet”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.
node<T>()
Section titled “node<T>()”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.
useData(options?)
Section titled “useData(options?)”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.
useDataProxy()
Section titled “useDataProxy()”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>().
useRouteInfo()
Section titled “useRouteInfo()”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. |