Skip to content

v0.7.3: client-side navigation for Svelte and MDX

3 min read

One feature in v0.7.3, closing a gap between the frameworks, and one fix.

React, SolidJS and Vue navigate through their own routers, and Link is that router's link component.

Svelte and MDX have no third-party router, so KosmoJS supplies the route matcher. Until now, it supplied nothing more: Link rendered a plain <a>, and following it was a full page load. The server rendered the next page, or the CSR shell did, and every layout mounted from scratch, losing whatever state it held.

Now they navigate in place ​

KosmoJS now intercepts navigations itself, through the browser's Navigation API.

One navigate listener covers link clicks, back and forward, location.assign() and GET form submissions. So links stay plain anchors, and a hand-written <a href> navigates client-side too, markdown links in MDX included.

On every navigation the router matches the URL, runs the loaders, then renders:

  • Layouts shared by both routes stay mounted, with their state.
  • The page mounts anew, even when only the query changed.
  • Scroll goes to the top, or the #fragment, for a new entry, and back to where it was for back and forward, once the new page is in the DOM.

What still loads from the server ​

Not everything is intercepted:

  • a URL no route of this source folder matches - another source folder, or a missing page, which gets the server's 404;
  • a fragment-only change, a download, a POST form and a reload;
  • a link marked data-reload, for a page that must come from the server:
svelte
<Link to={["reports/export"]} data-reload>Export</Link>

And when resolving fails, say a route chunk that is gone after a deploy, or a loader that throws, the page reloads, so the server renders the URL the address bar already shows.

A second click wins ​

Click one link, then another before the first page has rendered, and the first navigation is aborted. It never renders over the newer page.

Its loaders get an aborted signal. Pass it on to the fetch client, and the superseded request is cancelled too:

ts
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export const loader = ({ paramsEntries: [, values], signal }) => {
  return GET(values, {}, { signal });
};

Nothing breaks without it. The signal only saves the request.

_/use now exports navigate, taking the same tuple as Link:

ts
import { navigate } from "_/use";

await navigate(["users/[id]", 123], { query: { tab: "posts" } });
await navigate(["login"], { replace: true });

It resolves once the destination is rendered. Unlike the hooks, it can be called anywhere: an event handler, an effect, after an await.

Browsers without the Navigation API ​

Nothing is intercepted there, and every link is a full page load, as before. The app keeps working, served by SSR or the CSR shell.

The Navigation API has been in every major engine since early 2026.

SolidJS: preload on hover ​

A SolidJS page can export a preload, and SolidJS Router calls it on link hover and navigation intent, so the data is on its way before the click.

Only half of that held. KosmoJS gives the router a route preload that loads the page module, then runs the page's own. It loaded the module, but handed the page's preload back instead of calling it. So a hover fetched the route's code and nothing more, and the data only started loading once the page rendered after the click.

Now the page's preload runs on hover too. By the time you click, createAsync finds the data in the query cache, or already on its way.

Upgrading ​

Nothing to change. The listener comes with the derived client entry, and your own entry/client.ts stays as it is.

Two things are worth a look, though.

Svelte layouts follow the route now ​

A layout used to mount anew on every page load, so reading the route once, at init, was always current. Now a layout stays mounted across navigations, and a snapshot goes stale.

useRoute, useParams and useSearchParams return live views. Read them in markup or in $derived, and do not destructure them in a layout:

svelte
<script lang="ts">
import { useRoute } from "_/use";

const route = useRoute();
const { name } = useRoute();   // a snapshot - stale after a navigation

const title = $derived(route.name === "index" ? "Home" : route.name);
</script>

useLoaderData returns a snapshot too. A layout loader runs again on every navigation, so a layout reads its data through useRoute().loaderData[key] instead.

MDX layouts need nothing: a navigation re-renders the layouts it keeps.

Released under the MIT License.