Runtime API

These modules run in the browser. The generated client already starts the router or mounts islands, so most apps only use a few of these functions from islands. Everything is typed; this page lists what each export is for.

Router

getRouter(document?)

Returns the router started by the generated SPA client, or undefined in MPA builds and before it starts.

import { getRouter } from "fuzor/runtime";

const router = getRouter();
const outcome = await router?.navigate("/checkout/");
if (outcome?.status === "failed") console.error(outcome.error);

createRouter(outlet, options)

Creates a router for an outlet element. Only needed when you write your own client entry. Options:

Router methods

Subscriptions return a function that unsubscribes.

Typed links

href(pattern, params?, options?)

Builds an app URL from a route or endpoint pattern and encodes its parameters. With the generated .fuzor/routes.d.ts, unknown patterns and missing or extra parameters are type errors. options: base, search (object or URLSearchParams), hash. See typed links.

FuzorRoutes is the interface the generated file augments, and RoutePattern the union of its keys (or string without it).

URL state

makeNavigationUrlAtom(navigation, key, schema, initialValue, options?)

An Effect that creates a schema-checked value stored in one query parameter. It lives in the surrounding Effect scope.

import * as Effect from "effect/Effect";
import * as Schema from "effect/Schema";
import { getRouter, makeNavigationUrlAtom } from "fuzor/runtime";

const program = Effect.scoped(Effect.gen(function* () {
  const page = yield* makeNavigationUrlAtom(getRouter()!.navigation()!, "page", Schema.Number, 1);
  page.subscribe(value => console.log("page", value));
  yield* page.set(2);            // replaces the history entry; pass "push" to add one
  yield* page.remove();          // deletes ?page
  yield* Effect.never;           // keep the atom alive
}));

Values are stored as JSON. Other query parameters, the hash and history state are preserved. Invalid or repeated values fail creation with UrlAtomError unless options.invalid is "default"; later invalid URLs keep the last valid value and call options.onError.

Islands

Islands also emit a bubbling fuzor:hydration-mismatch event with { island, framework, error } when a preview does not match the browser render; see islands.

An island module exports mount(host, props), which may return a cleanup function or a promise of one, and optionally render(props, { id }) returning HTML or a promise of HTML at build time. See writing an island adapter.

Server data

See server data.

Navigation adapters

The router picks an adapter automatically: the browser Navigation API where available, the History API elsewhere, and fragment (hash) routing for file: or custom-protocol documents. For tests and non-browser hosts, create one yourself:

import * as Effect from "effect/Effect";
import { createRouter, makeMemoryNavigation } from "fuzor/runtime";

const navigation = await Effect.runPromise(makeMemoryNavigation({ baseUrl: "https://app.test/", initialEntries: [{ href: "/about/" }] }));
const router = createRouter(outlet, { navigation, islands });

Capacitor integration

import { App } from "@capacitor/app";
import { connectCapacitor, defaultDeepLink } from "fuzor/runtime/capacitor";

// Connects the started SPA router to Capacitor:
const disconnect = await connectCapacitor({
  app: App,
  rootBack: "exit", // "exit" (default) or "minimize" on the first page
  deepLink: defaultDeepLink // optional custom URL mapping
});

URL helpers

routeKey(pathname) and normalizePath(path) apply Fuzor's URL matching rules. normalizeBase, stripBase and withBase convert between app paths and deployment-base paths.