Signature

function watchDeployment(
  router: NavigationRouter,
  options: DeploymentOptions | null,
): () => void;

Parameters

Pass a Smolter navigation or data router and DeploymentOptions from virtual:smolter/deployment. Null metadata is a no-op for development and SSR. Install once before starting a manual router or creating its fetchers, or pass deployment metadata directly to mountApplication so recovery also covers the initial route import.

import deployment from "virtual:smolter/deployment";
import { watchDeployment } from "@kasperrt/smolter/preact/client";

const stop = watchDeployment(router, deployment);

Result and disposal

Returns a cleanup function. Cleanup removes the popstate and Vite listeners, aborts a pending manifest request and restores router methods. router.dispose() also calls cleanup. Installing a replacement watcher keeps submission protection for already tracked fetchers and allows the replacement to recover after they settle. Calling the previous cleanup function again does not stop the replacement.

stop();

Navigation behavior

Pathname/query navigation and Back/Forward compare destination dependencies and shared application fingerprints. Unrelated route changes keep client navigation. Changed shared code, changed/missing destinations, or missing compatibility metadata require document recovery. Routine checks run in the background and never delay navigation or Back/Forward. A discovered change applies on the next eligible navigation, not as a late reload of a successfully rendered page. Completed checks, including failures, are reused for 30 seconds (checkInterval); chunk failures bypass this interval. Hash-only/external links skip checks. Concurrent checks share a request; only the latest intent may reload. Mutations are never replayed.

Failures and cache policy

Network errors, bad JSON and timeouts fall back to normal navigation. A session marker limits recovery to one reload per old build/manifest URL. Blocked storage disables automatic reload. Serve the manifest with no-store and HTML with no-cache. A custom reload callback owns confirmation/navigation and receives the destination URL. Idle intent-prefetch failures do not reload the current page or consume the recovery marker. Recovery waits for navigation to record a destination; overlapping checks honor the newest navigation. New history operations invalidate pending checks even when returning to the current route. Starting a mutation cancels earlier recovery checks. Redirect chunk recovery uses the committed router URL, including query and hash, rather than the URL of the original click.

watchDeployment(router, deployment && { ...deployment, timeout: 1500 });