@k8ordo/router

Troubleshooting

Common symptoms, their causes and their fixes. To look up an error, search this page for its wording.

On this page

Full page reload on a link click

Cause

No pattern in the route table matches the link’s path. The router handles only navigations to paths the table matches. Everything else is an ordinary page load by the browser. When the app is served under a base, a path outside the base is left to the browser as well.

Fix

Add the pattern to the route table. If you build links with href and register the table on Register, a pattern missing from the table is a type error.

The /* page on a link to a file

Cause

The /* at the end of the route table matches every path, so the router handles a link to a file the host serves as well.

Fix

Give the link the download attribute. The browser treats the click as a download, and the router leaves it alone.

The /products/:id page at /products/new

Cause

The router checks the route table from the top and takes the first pattern that matches. With /products/:id written first, new matches :id.

Fix

Write a literal pattern such as /products/new before the :id pattern.

useParams(…) rendered under …

Cause

The pattern given to useParams is not the pattern of the page the component renders under. It happens in a component shared by several pages, or in a layout.

Fix

Call it in the page component, with that page’s pattern. In a component shared by several pages, read untyped params with useRoute, or check which page is open with useMatch.

useRoute must render inside a matched <Router>

Cause

useRoute and useParams read the match held by <Router>. Called outside <Router>, or under @k8ordo/framework, which has no <Router>, they throw this error.

Fix

In an app that mounts <Router> itself, call them under it. Under the framework, use usePathname or useMatch to know where you are in a Client Component. For how a page receives params, see Parameters.

usePathname needs <Router> above it

Cause

During a server render and hydration, the browser’s URL cannot be read. usePathname then reads the pathname provided by <Router> or by the framework’s runtime. With neither above it, this error is thrown.

Fix

Use it under <Router> or in a page the framework renders. In a host of your own built on useInterceptedNavigation, provide the pathname being rendered through <PathnameProvider>.

history ignored on a bound navigateTo

Cause

When the pattern has a parameter, the second argument is always read as params. This holds even when bindParams supplies every parameter, so a history passed second is ignored.

Fix

Pass undefined second and the options third. In TypeScript, options in second place are a type error.

Active link that changes before the page

Cause

A navigation changes the URL first, and the new page appears once it is ready. usePathname and useMatch read the URL, so they return the new pathname while the previous page is still on screen. This is the same order the browser’s address bar follows.

Fix

To show that a page is loading, read the pending pathname with usePendingPathname. For a navigation you started, await navigateTo’s finished.

A React.lazy page that shows nothing while loading

Cause

An object with an error wraps the pages below it in a <Suspense> whose fallback is null. When a React.lazy page suspends under it, that <Suspense> renders null, and the fallback of a layout’s <Suspense> above is never used.

Fix

Give the same object a loading, or put a <Suspense> below the error.

finished rejecting with AbortError

Cause

Another navigation started before this one finished. The overtaken navigation is aborted, and its finished rejects with the abort reason.

Fix

Where finished can be overtaken, ignore only a DOMException named AbortError, and rethrow anything else.

Page cross-fade on every button press

Cause

The <ViewTransition> runs for transitions other than page changes. A pending action of @k8ordo/ui’s Button is a transition too.

Fix

Set the <ViewTransition>’s default to none and pass { navigation: 'auto', default: 'none' } to update. It then runs only for the navigation transition type the router adds.

Error that stays after a query change

Cause

The route table’s error display clears when you move to another page. A state update that changes only the query is not a page change, so the display stays.

Fix

Call the reset the error component receives. The page renders again in place.

No type error for a pattern missing from the table

Cause

The file holding the Register augmentation is outside what TypeScript checks. Under the framework, Register is generated into .k8ordo. A directory whose name starts with a dot is skipped when include names only its parent directory.

Fix

Put the file inside what include covers. Under the framework, add the glob .k8ordo/**/*.ts to include.

k8ordo

React libraries that use Baseline features without holding back.